Skip to content

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].