feat(derive): preserve verbatim doc comments

[jdx]

Summary

• accept #[usage(verbatim_doc_comment)] on root and command structs, fields, and subcommand variants
• preserve internal line breaks, blank lines, indentation, and whitespace in derived help
• retain the conventional removal of one leading space after /// and outer blank lines
• document the attribute and cover root, flag, and subcommand metadata

This keeps Clap declarations that use ASCII art, tables, examples, or deliberately formatted prose intact during migration.

Stack

Targets #947 and becomes the direct base for #936.

Checks

• cargo test -p usage-conformance --test metadata
• cargo test -p usage-derive
• cargo test --all --all-features
• cargo clippy --all --all-features --all-targets -- -D warnings
• mise run render

This PR was generated by Codex.

---

Note

Low Risk
Changes are confined to derive-time help text extraction with default behavior preserved; risk is limited to help/spec wording, covered by new conformance tests.

Overview
Adds #[usage(verbatim_doc_comment)] on root/Args structs, fields, and subcommand variants so doc comments can feed help/about text with intentional line breaks, blank lines, and indentation instead of flowing the first paragraph like prose.

The derive’s doc_comment helper now takes a verbatim flag: default behavior is unchanged (first paragraph collapsed to one line for short help; multiline #[doc = "..."] still behaves as before). With verbatim, it strips only the usual /// leading space and outer blank lines, then splits short help at the first blank line and keeps the full text for long help when there is more.

Crate docs list the new option; conformance metadata tests cover root, flag, and subcommand specs plus ordinary vs verbatim multiline #[doc] attributes.

^{Reviewed by Cursor Bugbot for commit 641c80c. Bugbot is set up for automated code reviews on this repo. Configure here.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Central YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: 7936a722-2f8a-4152-b8bd-ac048903c48e

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[greptile-apps]

Greptile Summary

The PR adds opt-in verbatim preservation for derived doc-comment metadata while retaining existing default formatting behavior.

• Supports verbatim_doc_comment on root structs, fields, and subcommand variants.
• Preserves line breaks, blank lines, and indentation in verbatim help metadata.
• Adds conformance coverage for root, flag, subcommand, and explicit multiline #[doc] attributes.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
derive/src/model.rs	Adds verbatim-aware doc-comment parsing and resolves both previously reported indentation regressions.
conformance/tests/metadata.rs	Adds focused metadata tests confirming indentation preservation in ordinary and verbatim modes.
derive/src/lib.rs	Documents the new struct- and field-level verbatim doc-comment attribute.

_{Reviews (5): Last reviewed commit: "fix(derive): preserve verbatim continuat..." | Re-trigger Greptile}

[github-actions]

Instruction counts

Nothing was compared, and so nothing was gated. No series appears on both sides: either the base has no measurements recorded, or the two were measured on different runner classes, which are deliberately not comparable — counts shift between machine types by more than a real regression does.

New, nothing to compare against: markdown on bamboo-v2-ubuntu24.04-x64-30vcpu-24gb-rust1.97.1, startup on bamboo-v2-ubuntu24.04-x64-30vcpu-24gb-rust1.97.1

_{Only instruction counts gate. Wall clock is shown for context — on identical hardware it moves 4-20% run to run.}

_{Measured by tak — instruction-counted CLI benchmarks, stored in this repository's git notes.}

Shadow comparison

Parsing mise use -g node@20 against a shadow of mise's committed spec.
Reported, not gated: the shadow grows as the derive learns to express more, so
what to watch is the ratio rather than either column.

	usage	clap	ratio
instructions, cold parse	64525	5893640	91x

usage: argv -> struct                            1115 ns      1.12 µs
clap: build tree + parse -> struct             495723 ns    495.72 µs
clap: parse -> struct, tree reused              24431 ns     24.43 µs
clap: build tree only                          311378 ns    311.38 µs

_{641c80c6efb6 vs 60b4357913a5 · measured on the runner, not pushed to the history.}