C0021 cli-help-text¶
Rule: Every command and argument of a CLI has a help line.
| Code | C0021 (stable, never reused) |
| Id | cli-help-text |
| Category | cli |
| Source | spirit_level |
| Fix | by hand |
| Needs | cargo installed |
Level per tier¶
| Tier | Level | Reason |
|---|---|---|
| small | warn |
-h is the map of a tool; an entry without a line leaves the reader guessing |
| small-workspace | warn |
-h is the map of a tool; an entry without a line leaves the reader guessing |
| medium | warn |
-h is the map of a tool; an entry without a line leaves the reader guessing |
| big | warn |
-h is the map of a tool; an entry without a line leaves the reader guessing |
| ai | off | |
| embedded | off | |
| ui | off | |
| egui | off | |
| units-strict | off | |
| units-paranoid | off |
Why¶
-h is the map of a tool: one line per command and argument. An entry without a line forces the reader to guess or to open the source, and completion shows the same empty text beside the candidate. A help that exits non-zero, or is not in clap's layout, breaks scripts and the other help lints.
Example¶
Commands:
sync Bring the mirror up to date
prune <- no help line
Options:
-n, --name <NAME> <- no help line
How to fix¶
Give every subcommand and argument a doc comment (or about / help); the tool itself gets an about. clap's own notes ([default: x], [possible values: ...]) do not count as help. A binary that is not a clap CLI is left out with cli = false in the crate map (CLI checks).
Configure¶
Allow one finding in the code with // spirit-level: allow(cli-help-text) <reason> (waivers); the code works there too, as in [lints.C0021].