Add comments.

Author: starcke

extensions/ql-vscode/src/common/commands.ts

@@ -1,9 +1,18 @@
 import { CommandManager } from "../packages/commands";
 
+/**
+ * Contains type definitions for all commands used by the extension.
+ *
+ * To add a new command first define its type here, then provide
+ * the implementation in the corresponding `getCommands` function.
+ */
+
+// Commands directly in the extension
 export type ExtensionCommands = {
   "codeQL.openDocumentation": () => Promise<void>;
 };
 
+// Commands tied to variant analysis
 export type VariantAnalysisCommands = {
   "codeQL.openVariantAnalysisLogs": (
     variantAnalysisId: number,

extensions/ql-vscode/src/common/vscode/commands.ts

@@ -2,6 +2,10 @@ import { commands } from "vscode";
 import { commandRunner } from "../../commandRunner";
 import { CommandFunction, CommandManager } from "../../packages/commands";
 
+/**
+ * Intializes a command manager for VSCode, wrapping the commandRunner
+ * and vscode.executeCommand.
+ */
 export function initializeVSCodeCommandManager<
   Commands extends Record<string, CommandFunction>,
 >(): CommandManager<Commands> {

extensions/ql-vscode/src/packages/commands/CommandManager.ts

@@ -1,9 +1,25 @@
+/**
+ * Contains a generic implementation of typed commands.
+ *
+ * This allows different parts of the extension to register commands with a certain type,
+ * and then allow other parts to call those commands in a well-typed manner.
+ */
+
 export interface Disposable {
   dispose(): void;
 }
 
+/**
+ * A command function is a completely untyped command.
+ */
 export type CommandFunction = (...args: any[]) => Promise<unknown>;
 
+/**
+ * The command manager basically takes a single input, the type
+ * of all the known commands. The second parameter is provided by
+ * default (and should not be needed by the caller) it is a
+ * technicality to allow the type system to look up commands.
+ */
 export class CommandManager<
   Commands extends Record<string, CommandFunction>,
   CommandName extends keyof Commands & string = keyof Commands & string,
@@ -24,20 +40,29 @@ export class CommandManager<
     ) => Promise<Awaited<ReturnType<Commands[T]>>>,
   ) {}
 
+  /**
+   * Register a command with the specified name and implementation.
+   */
   registerCommand<T extends CommandName>(
     commandName: T,
     definition: Commands[T],
   ): void {
     this.commands.push(this.commandRegister(commandName, definition));
   }
 
+  /**
+   * Execute a command with the specified name and the provided arguments.
+   */
   executeCommand<T extends CommandName>(
     commandName: T,
     ...args: Parameters<Commands[T]>
   ): Promise<Awaited<ReturnType<Commands[T]>>> {
     return this.commandExecute(commandName, ...args);
   }
 
+  /**
+   * Dispose the manager, disposing all the registered commands.
+   */
   dispose(): void {
     this.commands.forEach((cmd) => {
       cmd.dispose();