C0022 cli-help-clean¶
Rule: A CLI's help holds no rustdoc leftovers.
| Code | C0022 (stable, never reused) |
| Id | cli-help-clean |
| Category | cli |
| Source | spirit_level |
| Fix | by hand |
| Needs | cargo installed |
Level per tier¶
| Tier | Level | Reason |
|---|---|---|
| small | warn |
rustdoc source in help hides the tool's description |
| small-workspace | warn |
rustdoc source in help hides the tool's description |
| medium | deny |
rustdoc source in help is a plain defect, fixed in a line |
| big | deny |
rustdoc source in help is a plain defect, fixed in a line |
| ai | off | |
| embedded | off | |
| ui | off | |
| egui | off | |
| units-strict | off | |
| units-paranoid | off |
Parameters¶
| Name | Type | Default | Meaning |
|---|---|---|---|
markers |
list of strings | ["```", "[", "]("] |
text that only rustdoc source has: code fences, intra-doc links |
Why¶
clap turns doc comments into help text. A struct flattened into the parser (#[command(flatten)]) brings its own rustdoc along: code fences, intra-doc links and doctests then open the tool's --help. The text was written for rustdoc, not for a terminal, and it hides the tool's real description.
Example¶
$ tool --help
The `--color` flag, flattened into a CLI's root parser ...
``` use clap::Parser; use vc_ui::{ColorChoice, ColorFlag};
How to fix¶
Set about and long_about explicitly where the root parser derives Parser (#[command(about = "...", long_about = None)]), so a flattened struct's documentation is not taken. Keep rustdoc out of argument help: give help = "..." where the doc comment is for the API. The parameter markers lists the text that marks rustdoc source.
Configure¶
[lints.cli-help-clean]
level = "deny"
markers = ["```", "[`", "`]("]
reason = "why this project wants it at this level"
Allow one finding in the code with // spirit-level: allow(cli-help-clean) <reason> (waivers); the code works there too, as in [lints.C0022].