diff --git a/_tools/check_docs.ts b/_tools/check_docs.ts index 88898a289a4b..2f0a171a4fd5 100644 --- a/_tools/check_docs.ts +++ b/_tools/check_docs.ts @@ -28,6 +28,7 @@ type DocNodeWithJsDoc = T & { const ENTRY_POINTS = [ "../async/mod.ts", "../bytes/mod.ts", + "../cli/mod.ts", "../collections/mod.ts", "../datetime/mod.ts", "../internal/mod.ts", diff --git a/cli/parse_args.ts b/cli/parse_args.ts index 2acdb0275af5..fa7c5af91197 100644 --- a/cli/parse_args.ts +++ b/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 extends Record ? TRecord extends infer InferredRecord ? { [Key in keyof InferredRecord]: Id } : 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 extends unknown ? (args: TValue) => unknown : never) extends (args: infer R) => unknown ? R extends Record ? 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; +/** @internal */ type Aliases = Partial< Record, TAliasNames | ReadonlyArray> >; @@ -126,6 +137,7 @@ type SpreadDefaults = TDefaults extends undefined ? TArgs /** * Defines the Record for the `default` option to add * auto-suggestion support for IDE's. + * @internal */ type Defaults = Id< UnionToIntersection< @@ -245,6 +257,7 @@ export type Args< : Record) >; +/** @internal */ type DoubleDash = { /** Contains all the arguments that appear after the double dash: "--". */ "--"?: Array; @@ -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"]); diff --git a/cli/prompt_secret.ts b/cli/prompt_secret.ts index e3e7011b81fe..f21414197506 100644 --- a/cli/prompt_secret.ts +++ b/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", diff --git a/cli/spinner.ts b/cli/spinner.ts index 0a68cbc5874e..282629724ad7 100644 --- a/cli/spinner.ts +++ b/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() {