fix(cli): wrap doc comments so -h help stays one line per flag#478
Conversation
clap merges multi-line `///` doc comments into one paragraph for short help (`-h`) and only splits on the first blank `///` line to produce a separate first-line summary. Several flags were written as one continuous paragraph, so `aube <cmd> -h` rendered them as 120+ char lines that wrapped awkwardly on standard terminals. Move the qualifier prose into a second paragraph so the short-help line stays a concise summary — same shape `update --latest` uses (PR #473). Flags fixed across `add`, `approve-builds`, `audit`, `clean`, `config list`, `dlx`, `find-hash`, `init`, `install`, `link`, `list`, `patch`, `patch-remove`, `publish`, `query`, `remove`, `run`, `store status`, `update`, `version`, `view`, plus the `ApproveBuilds` and `Check` subcommand summaries on the top-level `aube --help`. Regenerated `aube.usage.kdl` and `docs/cli/*` via `mise run render`. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Greptile SummaryThis PR reformats multi-line doc comments across 22 source files so that Confidence Score: 5/5Safe to merge — changes are purely documentation/comment reformatting with no functional impact. All changes are limited to doc comments and their derived generated outputs. No logic, data paths, or interfaces are touched. Content is semantically preserved across all 22 source files and the regenerated docs are consistent with the source. No files require special attention. Important Files Changed
Reviews (1): Last reviewed commit: "fix(cli): wrap doc comments so -h help s..." | Re-trigger Greptile |
Benchmark changesPublic ratios: warm installs vs Bun 7x -> 7x; warm installs vs pnpm 11x -> 10x.
3e243a3 vs b2a7c3f | aube/bun/pnpm | 3 scenarios | 3 runs | 500mbit/50ms | generated by Codex. |
Summary
clap merges multi-line
///doc comments into one paragraph for short help (-h) and only splits on the first blank///line to produce a separate first-line summary. Several flags across the CLI were written as one continuous paragraph, soaube <cmd> -hrendered them as 120+ char lines that wrapped awkwardly on standard terminals.This PR splits each offender's doc comment into a short summary line + blank
///separator + the longer prose — same shapeupdate --latestalready uses (precedent: #473).Flags fixed
add -g, --global,--no-save,--save-catalog,--save-catalog-name,-w, --workspaceapprove-builds [PKG]...(positional doc), plus the subcommand summary onaube --helpaudit --ignore-unfixablechecksubcommand summary onaube --helpclean -l, --lockfile(also reflects topurge)config list --all,--jsondlx -c, --shell-modefind-hash --jsoninit --init-package-managerinstall --fix-lockfile,--force,--lockfile-dir,--merge-git-branch-lockfiles,--resolution-mode,--verify-store-integritylink -g, --globallist --longpatch --ignore-existingpatch-remove [PACKAGES]...publish --force,--ignore-scripts,--jsonquery <SELECTOR>remove -w, --workspacerun --parallelstore statussubcommand summaryupdate -L, --latest(same fix as feat(cli): warn when aube update --depth is set #473, included here since that PR is still open)version [NEW_VERSION]view <PACKAGE>,[FIELD]Validation
cargo build --workspace— cleancargo clippy --all-targets -- -D warnings— cleancargo fmt --check— cleanfor cmd in $(aube --help | grep -E '^ [a-z]' | awk '{print $1}'); do aube "$cmd" -h 2>&1 | awk 'length > 120'; done | grep -vE '\[possible values:|\[aliases:'CLI docs regenerated via
mise run render(aube.usage.kdl,docs/cli/commands.json,docs/cli/*.md).Test plan
cargo build --workspacecargo clippy --all-targets -- -D warningscargo fmt --checkaube <cmd> -hfor every fixed subcommand to confirm short help is now one clean summary line andaube <cmd> --helpstill shows the full prose🤖 Generated with Claude Code
Note
Low Risk
Pure CLI help-text/doc updates plus regenerated docs/command metadata; no behavior or parsing logic changes, so risk is low aside from potential wording/regeneration drift.
Overview
Tightens CLI
-houtput by splitting many commands/flags’ descriptions into a short first-line summary plus separate long help, avoiding overly long wrapped lines in terminal help.Updates the usage spec (
aube.usage.kdl), clap doc comments across multiple command arg structs, and regenerates the derived CLI docs (docs/cli/*.md) anddocs/cli/commands.jsonto reflect the new short/long help text (includingapprove-builds,check,publish,install,run, etc.).Reviewed by Cursor Bugbot for commit 3e243a3. Bugbot is set up for automated code reviews on this repo. Configure here.