lablup / lablup/mlxcel

docs(cli): unify subcommand summary punctuation and add missing Examples blocks

Open Beginner friendly
#1,657 0 comments 0 reactions 0 assignees View on GitHub
priority:low status:ready type:docs
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.