Tidy up logging docs

Author: charisk

extensions/ql-vscode/src/common/logging/logger.ts

@@ -1,23 +1,34 @@
 export interface LogOptions {
-  /** If false, don't output a trailing newline for the log entry. Default true. */
+  // If false, don't output a trailing newline for the log entry. Default true.
   trailingNewline?: boolean;
 
-  /** If specified, add this log entry to the log file at the specified location. */
+  // If specified, add this log entry to the log file at the specified location.
   additionalLogLocation?: string;
 }
 
 export interface Logger {
-  /** Writes the given log message, optionally followed by a newline. */
+  /**
+   * Writes the given log message, optionally followed by a newline.
+   * This function is asynchronous and will only resolve once the message is written
+   * to the side log (if required). It is not necessary to await the results of this
+   * function if you don't need to guarantee that the log writing is complete before
+   * continuing.
+   *
+   * @param message The message to log.
+   * @param options Optional settings.
+   */
   log(message: string, options?: LogOptions): Promise<void>;
+
   /**
-   * Reveal this channel in the UI.
+   * Reveal the logger channel in the UI.
    *
    * @param preserveFocus When `true` the channel will not take focus.
    */
   show(preserveFocus?: boolean): void;
 
   /**
-   * Remove the log at the specified location
+   * Remove the log at the specified location.
+   *
    * @param location log to remove
    */
   removeAdditionalLogLocation(location: string | undefined): void;

extensions/ql-vscode/src/common/logging/vscode/loggers.ts

@@ -1,15 +1,19 @@
+/**
+ * This module contains instantiated loggers to use in the extension.
+ */
+
 import { OutputChannelLogger } from "./output-channel-logger";
 
-/** The global logger for the extension. */
+// Global logger for the extension.
 export const logger = new OutputChannelLogger("CodeQL Extension Log");
 
-/** The logger for messages from the query server. */
+// Logger for messages from the query server.
 export const queryServerLogger = new OutputChannelLogger("CodeQL Query Server");
 
-/** The logger for messages from the language server. */
+// Logger for messages from the language server.
 export const ideServerLogger = new OutputChannelLogger(
   "CodeQL Language Server",
 );
 
-/** The logger for messages from tests. */
+// Logger for messages from tests.
 export const testLogger = new OutputChannelLogger("CodeQL Tests");

extensions/ql-vscode/src/common/logging/vscode/output-channel-logger.ts

@@ -4,7 +4,9 @@ import * as path from "path";
 import { Logger, LogOptions } from "../logger";
 import { DisposableObject } from "../../../pure/disposable-object";
 
-/** A logger that writes messages to an output channel in the Output tab. */
+/**
+ * A logger that writes messages to an output channel in the VS Code Output tab.
+ */
 export class OutputChannelLogger extends DisposableObject implements Logger {
   public readonly outputChannel: OutputChannel;
   private readonly additionalLocations = new Map<
@@ -20,12 +22,6 @@ export class OutputChannelLogger extends DisposableObject implements Logger {
     this.isCustomLogDirectory = false;
   }
 
-  /**
-   * This function is asynchronous and will only resolve once the message is written
-   * to the side log (if required). It is not necessary to await the results of this
-   * function if you don't need to guarantee that the log writing is complete before
-   * continuing.
-   */
   async log(message: string, options = {} as LogOptions): Promise<void> {
     try {
       if (options.trailingNewline === undefined) {
@@ -82,9 +78,7 @@ export class OutputChannelLogger extends DisposableObject implements Logger {
 }
 
 class AdditionalLogLocation {
-  constructor(private location: string) {
-    /**/
-  }
+  constructor(private location: string) {}
 
   async log(message: string, options = {} as LogOptions): Promise<void> {
     if (options.trailingNewline === undefined) {