Skip to content

Commit a3ac06b

Browse files
committed
docs: document undocumented features in README
1 parent 37da686 commit a3ac06b

File tree

1 file changed

+28
-9
lines changed

1 file changed

+28
-9
lines changed

README.md

Lines changed: 28 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -453,7 +453,7 @@ _Cleye_ uses all information provided to generate rich help documentation. The m
453453
#### Help customization
454454
The help document can be customized by passing a `render(nodes, renderers) => string` function to `help.render`.
455455

456-
The `nodes` parameter contains an array of nodes that will be used to render the document. The `renderers` parameter is an object of functions used to render the document. Each node has properties `type` and `data`, where `type` corresponds to a property in `renderers` and `data` is passed into the render function.
456+
The `nodes` parameter contains an array of nodes that will be used to render the document. The `renderers` parameter is an object of functions used to render the document. Each node has properties `type` and `data`, where `type` corresponds to a property in `renderers` and `data` is passed into the render function. Nodes also have an `id` property to identify sections: `name`, `description`, `usage`, `commands`, `flags`, `examples`, and `aliases`.
457457

458458
Default renderers can be found in [`/src/render-help/renderers.ts`](/src/render-help/renderers.ts).
459459

@@ -521,8 +521,8 @@ type ParsedArgv = {
521521
// Method to print version
522522
showVersion: () => void
523523

524-
// Method to print help
525-
showHelp: (options: HelpOptions) => void
524+
// Method to print help (pass HelpOptions to override content)
525+
showHelp: (options?: HelpOptions) => void
526526
}
527527
```
528528
@@ -581,7 +581,7 @@ Type: `false` or an object with the following properties.
581581
| - | - | - |
582582
| `version` | `string` | Version shown in `--help`. |
583583
| `description` | `string` | Description shown in `--help`. |
584-
| `usage` | `string \| string[]` | Usage code examples shown in `--help`. |
584+
| `usage` | `string \| string[] \| false` | Usage code examples shown in `--help`. Pass `false` to disable auto-generated usage. |
585585
| `examples` | `string \| string[]` | Example code snippets shown in `--help`. |
586586
| `render` | `(nodes, renderers) => string` | Function to customize the help document. |
587587
@@ -606,11 +606,17 @@ type IgnoreArgvCallback = (
606606
607607
A callback to ignore argv tokens from being parsed.
608608
609+
##### strictFlags
610+
611+
Type: `boolean`
612+
613+
When enabled, prints an error and exits if unknown flags are passed. Suggests the closest matching flag name when possible. See [Strict flags](#strict-flags).
614+
609615
#### callback(parsed)
610616
611-
Type:
617+
Type:
612618
613-
Optional callback function that is called when the script is invoked without a command.
619+
Optional callback function that is called when the script is invoked without a command. If the callback returns a Promise, the `cli()` return value will also be a Promise, allowing `await cli(...)` for async workflows.
614620
615621
#### argvs
616622
@@ -627,16 +633,29 @@ The raw parameters array to parse.
627633
| Property | Type | Description |
628634
| - | - | - |
629635
| `name` | `string` | Required name used to invoke the command. |
630-
| `alias` | `string \| string[]` | Aliases used to invoke the command. |
636+
| `alias` | `string \| string[]` | Aliases used to invoke the command. Displayed in an "Aliases:" section in `--help`. |
631637
| `parameters` | `string[]` | Parameters for the command. Same as [`parameters`](#parameters-1). |
632638
| `flags` | `Flags` | Flags for the command. Same as [`flags`](#flags-1). |
633639
| `help` | `false \| HelpOptions` | Help options for the command. Same as [`help`](#help-1). |
640+
| `ignoreArgv` | `IgnoreArgvCallback` | Same as [`ignoreArgv`](#ignoreargv). |
641+
| `strictFlags` | `boolean` | Same as [`strictFlags`](#strictflags). Inherits from parent CLI if not specified. |
634642
635643
#### callback(parsed)
636644
637-
Type:
645+
Type:
646+
647+
Optional callback function that is called when the command is invoked. If the callback returns a Promise, the `cli()` return value will also be a Promise.
648+
649+
### Type exports
650+
The following types are exported for use in TypeScript:
651+
652+
```ts
653+
import type { Flags, Renderers, TypeFlag } from 'cleye'
654+
```
638655

639-
Optional callback function that is called when the command is invoked.
656+
- `Flags` — Type for the `flags` option object.
657+
- `Renderers` — Class type for help document renderers, useful when customizing `help.render`.
658+
- `TypeFlag` — Re-exported from [`type-flag`](https://github.com/privatenumber/type-flag) for portable type declarations.
640659

641660
## Sponsors
642661
<p align="center">

0 commit comments

Comments
 (0)