From fa006a59d21189c9eaadbdcf8e0fc2816ced0170 Mon Sep 17 00:00:00 2001 From: Jefferson Rylee Date: Fri, 29 Mar 2024 20:04:43 +0800 Subject: [PATCH] Update doc comments, move spec() up the file --- src/core/argstree.ts | 2 +- src/core/core.types.ts | 11 ++++++----- src/core/error.ts | 11 ++++------- src/core/spec.ts | 18 +++++++++--------- src/core/spec.types.ts | 8 ++++---- src/core/stringify.ts | 2 +- 6 files changed, 25 insertions(+), 27 deletions(-) diff --git a/src/core/argstree.ts b/src/core/argstree.ts index bcaf64e..9959f07 100644 --- a/src/core/argstree.ts +++ b/src/core/argstree.ts @@ -5,7 +5,7 @@ import { Node, Options } from './core.types.js'; /** * Parse arguments into a tree structure. * @param args The arguments to parse. - * @param options The options object. + * @param options The {@linkcode Options} object. * @returns The {@linkcode Node} object. */ export function argstree(args: readonly string[], options: Options = {}): Node { diff --git a/src/core/core.types.ts b/src/core/core.types.ts index fe59cfb..79a181e 100644 --- a/src/core/core.types.ts +++ b/src/core/core.types.ts @@ -7,7 +7,7 @@ export interface NodeData { */ raw: string | null; /** - * The alias used to parse the options for this Node. + * The alias used to parse the options for this node. * Otherwise, this value is `null`. */ alias: string | null; @@ -22,7 +22,7 @@ export interface NodeData { } /** - * ArgsTree options. + * The ArgsTree options. */ export interface Options { /** @@ -54,7 +54,7 @@ export interface Options { * arguments for the parent option or command instead. * * Direct assignment with `=` will always read the - * assigned value as an argument for the option or command. + * assigned value as an argument for this option or command. * * An error is thrown if this option or command does not satisfy this condition. */ @@ -76,7 +76,8 @@ export interface Options { * * e.g. `--foo=value`, `foo=value` * - * By default, this option is set to `true` if the parsed argument starts with a dash (`-`). + * By default, this option is set to `true` if the parsed argument + * is an alias or an option (e.g. `-f`, `--foo`). */ assign?: boolean; /** @@ -95,7 +96,7 @@ export interface Options { * * ```javascript * [ - * ['--foo', 'arg1', 'arg2', ...], + * ['--option', 'arg1', 'arg2', ...], * ['command', 'arg1', 'arg2', ...], * ... * ] diff --git a/src/core/error.ts b/src/core/error.ts index 677cc51..fd8f121 100644 --- a/src/core/error.ts +++ b/src/core/error.ts @@ -6,7 +6,6 @@ import { NodeData, Options } from './core.types.js'; export interface ArgsTreeErrorOptions extends NodeData { /** * The cause error string. - * * - {@linkcode ArgsTreeError.VALIDATE_ERROR} * - {@linkcode ArgsTreeError.INVALID_OPTIONS_ERROR} * - {@linkcode ArgsTreeError.INVALID_RANGE_ERROR} @@ -26,13 +25,13 @@ export interface ArgsTreeErrorOptions extends NodeData { */ export interface ArgsTreeErrorObject extends ArgsTreeErrorOptions { /** - * The Error name. + * The error name. */ name: string; } /** - * ArgsTree error. + * The ArgsTree error. */ export class ArgsTreeError extends Error implements ArgsTreeErrorObject { /** @@ -40,7 +39,7 @@ export class ArgsTreeError extends Error implements ArgsTreeErrorObject { */ static readonly VALIDATE_ERROR = 'validate'; /** - * The options object provided is not valid. + * The {@linkcode Options} object provided is not valid. * * e.g. Incorrect {@linkcode Options.min min} and {@linkcode Options.max max} range. */ @@ -62,10 +61,8 @@ export class ArgsTreeError extends Error implements ArgsTreeErrorObject { * an option or command from {@linkcode Options.args}. */ static readonly UNRECOGNIZED_ARGUMENT_ERROR = 'unrecognized-argument'; - /** * The cause error string. - * * - {@linkcode ArgsTreeError.VALIDATE_ERROR} * - {@linkcode ArgsTreeError.INVALID_OPTIONS_ERROR} * - {@linkcode ArgsTreeError.INVALID_RANGE_ERROR} @@ -80,7 +77,7 @@ export class ArgsTreeError extends Error implements ArgsTreeErrorObject { options: Options; /** - * ArgsTree error. + * The ArgsTree error. * @param options The error options. */ constructor(options: ArgsTreeErrorOptions) { diff --git a/src/core/spec.ts b/src/core/spec.ts index c61a1d0..4a02f95 100644 --- a/src/core/spec.ts +++ b/src/core/spec.ts @@ -5,6 +5,15 @@ import { NodeData, Options } from './core.types.js'; import { ArgsTreeError } from './error.js'; import { Spec, SpecOptions } from './spec.types.js'; +/** + * Build the parse spec {@linkcode Options options} for {@linkcode argstree}. + * @param options The Spec options. + * @returns The Spec object. + */ +export function spec(options?: SpecOptions): Spec { + return _spec(null, normalize(options)); +} + function normalize(options: SpecOptions | undefined) { const opts: Options = {}; if (!options) { @@ -28,15 +37,6 @@ function normalize(options: SpecOptions | undefined) { return opts; } -/** - * Build {@linkcode Options options} for {@linkcode argstree}. - * @param options The spec options. - * @returns The spec object. - */ -export function spec(options?: SpecOptions): Spec { - return _spec(null, normalize(options)); -} - // NOTE: always keep reference to _options // direct mutation should be safe since this is internal function _spec(raw: string | null, _options: Options): Spec { diff --git a/src/core/spec.types.ts b/src/core/spec.types.ts index abe6f5a..fdb4835 100644 --- a/src/core/spec.types.ts +++ b/src/core/spec.types.ts @@ -3,12 +3,12 @@ import { argstree } from './argstree.js'; import { Node, NodeData, Options } from './core.types.js'; /** - * The spec options. + * The Spec options. */ export interface SpecOptions extends Omit {} /** - * The spec object. + * The Spec object. */ export interface Spec { /** @@ -63,7 +63,7 @@ export interface Spec { /** * Add an {@linkcode Options.args} function. * Additional calls will replace the existing {@linkcode handler}. - * @param handler The handler function. + * @param handler The `args` function. * @param data The Node data. * @returns `this` for chaining. */ @@ -80,7 +80,7 @@ export interface Spec { * * This is an alias for {@linkcode argstree} call: * ```javascript - * argstree(args, spec.build()); + * argstree(args, spec.options()); * ``` * @param args The arguments to parse. * @returns The {@linkcode Node} object. diff --git a/src/core/stringify.ts b/src/core/stringify.ts index dd38b4c..3ce6123 100644 --- a/src/core/stringify.ts +++ b/src/core/stringify.ts @@ -25,7 +25,7 @@ export interface StringifyOptions { /** * Create a tree structure string from the provided {@linkcode node}. - * @param node The Node object. + * @param node The {@linkcode Node} object. * @param options The stringify options. * @returns The tree string. */