docs(cli): make check_docs pass (#4815)

_tools/check_docs.ts

@@ -28,6 +28,7 @@ type DocNodeWithJsDoc<T = DocNodeBase> = T & {
 const ENTRY_POINTS = [
   "../async/mod.ts",
   "../bytes/mod.ts",
+  "../cli/mod.ts",
   "../collections/mod.ts",
   "../datetime/mod.ts",
   "../internal/mod.ts",

cli/parse_args.ts

@@ -18,24 +18,33 @@
  */
 import { assert } from "@std/assert/assert";
 
-/** Combines recursively all intersection types and returns a new single type. */
+/** Combines recursively all intersection types and returns a new single type.
+ * @internal
+ */
 type Id<TRecord> = TRecord extends Record<string, unknown>
   ? TRecord extends infer InferredRecord
     ? { [Key in keyof InferredRecord]: Id<InferredRecord[Key]> }
   : never
   : TRecord;
 
-/** Converts a union type `A | B | C` into an intersection type `A & B & C`. */
+/** Converts a union type `A | B | C` into an intersection type `A & B & C`.
+ * @internal
+ */
 type UnionToIntersection<TValue> =
   (TValue extends unknown ? (args: TValue) => unknown : never) extends
     (args: infer R) => unknown ? R extends Record<string, unknown> ? R : never
     : never;
 
+/** @internal */
 type BooleanType = boolean | string | undefined;
+/** @internal */
 type StringType = string | undefined;
+/** @internal */
 type ArgType = StringType | BooleanType;
 
+/** @internal */
 type Collectable = string | undefined;
+/** @internal */
 type Negatable = string | undefined;
 
 type UseTypes<
@@ -52,6 +61,7 @@ type UseTypes<
 /**
  * Creates a record with all available flags with the corresponding type and
  * default type.
+ * @internal
  */
 type Values<
   TBooleans extends BooleanType,
@@ -79,6 +89,7 @@ type Values<
   // deno-lint-ignore no-explicit-any
   : Record<string, any>;
 
+/** @internal */
 type Aliases<TArgNames = string, TAliasNames extends string = string> = Partial<
   Record<Extract<TArgNames, string>, TAliasNames | ReadonlyArray<TAliasNames>>
 >;
@@ -126,6 +137,7 @@ type SpreadDefaults<TArgs, TDefaults> = TDefaults extends undefined ? TArgs
 /**
  * Defines the Record for the `default` option to add
  * auto-suggestion support for IDE's.
+ * @internal
  */
 type Defaults<TBooleans extends BooleanType, TStrings extends StringType> = Id<
   UnionToIntersection<
@@ -245,6 +257,7 @@ export type Args<
     : Record<never, never>)
 >;
 
+/** @internal */
 type DoubleDash = {
   /** Contains all the arguments that appear after the double dash: "--". */
   "--"?: Array<string>;
@@ -420,13 +433,28 @@ const FLAG_REGEXP =
  * Numeric-looking arguments will be returned as numbers unless `options.string`
  * or `options.boolean` is set for that argument name.
  *
- * @example
+ * @param args An array of command line arguments.
+ *
+ * @typeParam TArgs Type of result.
+ * @typeParam TDoubleDash Used by `TArgs` for the result.
+ * @typeParam TBooleans Used by `TArgs` for the result.
+ * @typeParam TStrings Used by `TArgs` for the result.
+ * @typeParam TCollectable Used by `TArgs` for the result.
+ * @typeParam TNegatable Used by `TArgs` for the result.
+ * @typeParam TDefaults Used by `TArgs` for the result.
+ * @typeParam TAliases Used by `TArgs` for the result.
+ * @typeParam TAliasArgNames Used by `TArgs` for the result.
+ * @typeParam TAliasNames Used by `TArgs` for the result.
+ *
+ * @return The parsed arguments.
+ *
+ * @example Usage
  * ```ts
  * import { parseArgs } from "@std/cli/parse-args";
  * const parsedArgs = parseArgs(Deno.args);
  * ```
  *
- * @example
+ * @example Usage
  * ```ts
  * import { parseArgs } from "@std/cli/parse-args";
  * const parsedArgs = parseArgs(["--foo", "--bar=baz", "./quux.txt"]);

cli/prompt_secret.ts

@@ -27,6 +27,19 @@ export type PromptSecretOptions = {
  * Shows the given message and waits for the user's input. Returns the user's input as string.
  * This is similar to `prompt()` but it print user's input as `*` to prevent password from being shown.
  * Use an empty `mask` if you don't want to show any character.
+ *
+ * @param message The prompt message to show to the user.
+ * @returns The string that was entered or `null` if stdin is not a TTY.
+ *
+ * @example Usage
+ * ```ts no-eval
+ * import { promptSecret } from "@std/cli/prompt-secret";
+ *
+ * const password = promptSecret("Please provide the password:");
+ * if (password !== "some-password") {
+ *   throw new Error("Access denied.");
+ * }
+ * ```
  */
 export function promptSecret(
   message = "Secret",

cli/spinner.ts

@@ -71,20 +71,29 @@ export interface SpinnerOptions {
 
 /**
  * A spinner that can be used to indicate that something is loading.
+ *
+ * @example Usage
+ * ```ts no-eval
+ * import { Spinner } from "@std/cli/spinner";
+ *
+ * const spinner = new Spinner({ message: "Loading...", color: "yellow" });
+ * spinner.start();
+ *
+ * setTimeout(() => {
+ *  spinner.stop();
+ *  console.log("Finished loading!");
+ * }, 3_000);
+ * ```
  */
 export class Spinner {
   #spinner: string[];
-  #interval: number;
-  #color?: Color;
-  #intervalId: number | undefined;
-  #active = false;
 
   /**
    * The message to display next to the spinner.
    * This can be changed while the spinner is active.
    *
-   * @example
-   * ```ts
+   * @example Usage
+   * ```ts no-eval
    * import { Spinner } from "@std/cli/spinner";
    *
    * const spinner = new Spinner({ message: "Working..." });
@@ -101,12 +110,17 @@ export class Spinner {
    * console.log("Done!");
    * ```
    */
-  message: string = "";
+  message: string;
+
+  #interval: number;
+  #color?: Color;
+  #intervalId: number | undefined;
+  #active = false;
 
   /**
    * Creates a new spinner.
    *
-   * @example
+   * @example Usage
    * ```ts
    * import { Spinner } from "@std/cli/spinner";
    *
@@ -130,8 +144,12 @@ export class Spinner {
    * Set the color of the spinner. This defaults to the default terminal color.
    * This can be changed while the spinner is active.
    *
-   * @example
-   * ```ts
+   * Providing `undefined` will use the default terminal color.
+   *
+   * @param value Color to set.
+   *
+   * @example Usage
+   * ```ts no-eval
    * import { Spinner } from "@std/cli/spinner";
    *
    * const spinner = new Spinner({ message: "Loading...", color: "yellow" });
@@ -149,6 +167,15 @@ export class Spinner {
 
   /**
    * Get the current color of the spinner.
+   *
+   * @example Usage
+   * ```ts
+   * import { Spinner } from "@std/cli/spinner";
+   *
+   * const spinner = new Spinner({ message: "Loading", color: "blue" });
+   * console.log(spinner.color); // "blue"
+   * ```
+   * @returns The color of the spinner or `undefined` if it's using the terminal default.
    */
   get color(): Color | undefined {
     return this.#color;
@@ -157,8 +184,8 @@ export class Spinner {
   /**
    * Starts the spinner.
    *
-   * @example
-   * ```ts
+   * @example Usage
+   * ```ts no-eval
    * import { Spinner } from "@std/cli/spinner";
    *
    * const spinner = new Spinner({ message: "Loading..." });
@@ -193,8 +220,8 @@ export class Spinner {
   /**
    * Stops the spinner.
    *
-   * @example
-   * ```ts
+   * @example Usage
+   * ```ts no-eval
    * import { Spinner } from "@std/cli/spinner";
    *
    * const spinner = new Spinner({ message: "Loading..." });
@@ -203,7 +230,7 @@ export class Spinner {
    * setTimeout(() => {
    *  spinner.stop();
    *  console.log("Finished loading!");
-   * }, 3000);
+   * }, 3_000);
    * ```
    */
   stop() {