docs(cli): unify subcommand summary punctuation and add missing Examples blocks
- Dominant language
- Rust
- Stars
- 467
- Forks
- 54
- Avg merge
- 4h 25m
- Merged PRs (30d)
- 310
Description
## Summary
The subcommand summaries in `mlxcel --help` are inconsistently styled: some are bare one-line summaries with no trailing period and no `Examples:` block, while others carry a trailing period, an extended description, and an `Examples:` block. The top-level help reads as two different documentation styles. This brings the bare variants up to the fuller style.
## Background
The CLI's `Commands` enum in `src/main.rs` derives help text from doc comments. Roughly half the subcommands follow a full template (summary with trailing period, extended paragraph, `Examples:` block guarded by `#[command(verbatim_doc_comment)]`) and half do not. A consistent help surface is easier to read and sets a clear pattern for new subcommands.
## Proposed Solution
Adopt the fuller style for the five bare variants: add the trailing period, a short extended description where useful, and an `Examples:` block with at least one real invocation. Add `#[command(verbatim_doc_comment)]` where the example formatting requires it. This is a doc-comment change only, no logic.
## Implementation Notes
- Bare variants to upgrade (no trailing period, no `Examples:` block): `Generate` (`src/main.rs:105`), `Serve` (`:109`), `List` (`:112`), `Arch` (`:116`), `Download` (`:135`). Line numbers are approximate; match by variant name.
- In-file templates to imitate: `Inspect` (`:120`) and `Detect` (`:138`) both carry the full style, and the `Embed`/`Rerank`/`Rm`/`Tune` variants further down follow it too. The file currently has 7 `Examples:` blocks to copy from.
- Keep example invocations realistic (model paths and flags that actually exist for each subcommand), matching the style of the existing blocks.
- `tests/cli_help_consistency.rs` exercises the help surface; run it after the change.
## Acceptance Criteria
- [ ] Every subcommand summary in `mlxcel --help` ends consistently, and each subcommand's long help carries at least one example invocation
- [ ] `tests/cli_help_consistency.rs` still passes
---
## Original Suggestion
### Title: docs(cli): unify subcommand summary punctuation and add missing Examples blocks
The subcommand summaries in `mlxcel --help` are inconsistently punctuated, and about half the subcommands have no `Examples:` block while the other half do — so the top-level help reads as two different styles.
## Evidence
In the `Commands` enum of `src/main.rs`:
- Bare one-line summaries, no trailing period, no `Examples:` block: `Generate` (`src/main.rs:105`), `Serve` (`:109`), `List` (`:112`), `Arch` (`:116`), `Download` (`:135`)
- Full style with trailing period, extended description, and `Examples:` block: `Inspect` (`:120`), `Detect` (`:138`), and the `Embed`/`Rerank`/`Rm`/`Tune` variants further down (7 `Examples:` blocks exist in the file)
## Suggested fix
Adopt the fuller style for the five bare variants: add the trailing period and a short `Examples:` block (with `#[command(verbatim_doc_comment)]` where needed), imitating the six in-file templates. Doc comments only, no logic.
## Acceptance criteria
- [ ] Every subcommand summary in `mlxcel --help` ends consistently and each subcommand's long help carries at least one example invocation
- [ ] `tests/cli_help_consistency.rs` still passes
Contributor guide
Research direction
Start in the Commands enum in src/main.rs, comparing the Generate, Serve, List, Arch, and Download doc comments with the existing Inspect, Detect, Embed, Rerank, Rm, and Tune templates. Use realistic supported invocations and run tests/cli_help_consistency.rs; done means every subcommand help summary is consistently punctuated and includes an Examples block.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- cli, documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 88/100