From 209cb19d83185ea8c323aaabc68de4dd682d0d73 Mon Sep 17 00:00:00 2001
From: Lev Chelyadinov <leva181777@gmail.com>
Date: Sun, 20 Feb 2022 23:02:56 +0300
Subject: [PATCH] chore: document the interface of command packages (#3828)

---
 packages/pnpm/src/cmd/index.ts | 37 +++++++++++++++++++++++++++++-----
 1 file changed, 32 insertions(+), 5 deletions(-)

diff --git a/packages/pnpm/src/cmd/index.ts b/packages/pnpm/src/cmd/index.ts
index 5f8e174359..f02cc388e4 100644
--- a/packages/pnpm/src/cmd/index.ts
+++ b/packages/pnpm/src/cmd/index.ts
@@ -54,15 +54,42 @@ export type Command = (
   params: string[]
 ) => CommandResponse | Promise<CommandResponse>
 
-const commands: Array<{
-  cliOptionsTypes: () => Object
-  commandNames: string[]
-  completion?: CompletionFunc
+export interface CommandDefinition {
+  /** The main logic of the command. */
   handler: Function
+  /** The help text for the command that describes its usage and options. */
   help: () => string
+  /** The names that will trigger this command handler. */
+  commandNames: string[]
+  /**
+   * A function that returns an object whose keys are acceptable CLI options
+   * for this command and whose values are the types of values
+   * for these options for validation.
+   */
+  cliOptionsTypes: () => Object
+  /**
+   * A function that returns an object whose keys are acceptable options
+   * in the .npmrc file for this command and whose values are the types of values
+   * for these options for validation.
+   */
   rcOptionsTypes: () => Record<string, unknown>
+  /** Auto-completion provider for this command. */
+  completion?: CompletionFunc
+  /**
+   * Option names that will resolve into one or more of the other options.
+   *
+   * Example:
+   * ```ts
+   * {
+   *   D: '--dev',
+   *   parallel: ['--no-sort', '--recursive'],
+   * }
+   * ```
+   */
   shorthands?: Record<string, string | string[]>
-}> = [
+}
+
+const commands: CommandDefinition[] = [
   add,
   audit,
   bin,