Update doc comments, move spec() up the file

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 {

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', ...],
    *   ...
    * ]

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,21 +25,21 @@ 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 {
   /**
    * Validation failed from provided {@linkcode Options.validate} function.
    */
   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) {

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 {

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<Options, 'alias' | 'args'> {}
 
 /**
- * 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.

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.
  */