docs: add documentation to public API structs #455
Conversation
Add comprehensive doc comments to the main public API types: - SpecFlag: CLI flag/option specification with field-level docs - SpecArg: Positional argument specification with field-level docs - SpecCommand: Command/subcommand specification with field-level docs Each struct now includes: - A description of what it represents - A usage example with the builder pattern - Documentation for each public field Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
This PR adds comprehensive documentation to the main public API types (SpecFlag, SpecArg, and SpecCommand) to improve discoverability and IDE support. Each struct now includes a high-level description, usage examples demonstrating the builder pattern, and field-level documentation explaining purpose and behavior.
Changes:
- Added struct-level and field-level documentation to
SpecFlag - Added struct-level and field-level documentation to
SpecArg - Added struct-level and field-level documentation to
SpecCommand
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
| lib/src/spec/flag.rs | Added comprehensive documentation to SpecFlag struct including all fields (name, usage, help variants, short/long, required, deprecated, var, hide, global, count, arg, default, negate, env) |
| lib/src/spec/arg.rs | Added comprehensive documentation to SpecArg struct including all fields (name, usage, help variants, required, double_dash, var, hide, default, choices, env) |
| lib/src/spec/cmd.rs | Added comprehensive documentation to SpecCommand struct including all fields (full_cmd, usage, subcommands, args, flags, mounts, deprecated, hide, subcommand_required, restart_token, help variants, name, aliases, examples, complete) |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| /// ``` | ||
| #[derive(Debug, Default, Clone, Serialize)] | ||
| pub struct SpecFlag { | ||
| /// Internal name for the flag (derived from long/short if not set) |
There was a problem hiding this comment.
The comment states the name is "derived from long/short if not set", but this field doesn't have a default derivation mechanism visible in the struct definition. Consider clarifying whether this derivation happens in the builder or constructor, or if this field must be explicitly set.
| /// Internal name for the flag (derived from long/short if not set) | |
| /// Internal name for the flag (typically derived from long/short by the builder) |
| pub struct SpecFlag { | ||
| /// Internal name for the flag (derived from long/short if not set) | ||
| pub name: String, | ||
| /// Generated usage string (e.g., "-v, --verbose") |
There was a problem hiding this comment.
The documentation says "Generated usage string" but this is a public field that can be set directly. Consider clarifying that this is typically auto-generated but can be overridden, or document when/how the generation occurs.
| /// Generated usage string (e.g., "-v, --verbose") | |
| /// Usage string (e.g., "-v, --verbose"), typically auto-generated from the flag names but can be set manually |
| pub struct SpecArg { | ||
| /// Name of the argument (used in help text) | ||
| pub name: String, | ||
| /// Generated usage string (e.g., "<file>" or "[file]") |
There was a problem hiding this comment.
Similar to the flag's usage field, the documentation says "Generated" but this is a public field. Consider clarifying that this is typically auto-generated (as seen in the usage() method in the context) but can be manually set.
| /// Generated usage string (e.g., "<file>" or "[file]") | |
| /// Usage string (e.g., "<file>" or "[file]"); typically auto-generated but can be set manually |
| pub struct SpecCommand { | ||
| /// Full command path from root (e.g., ["git", "remote", "add"]) | ||
| pub full_cmd: Vec<String>, | ||
| /// Generated usage string |
There was a problem hiding this comment.
The documentation says "Generated usage string" but this is a public field. Consider clarifying that this is typically auto-generated (as seen in the usage() method in the context) but can be manually set.
| /// Generated usage string | |
| /// Usage string for this command. | |
| /// | |
| /// This is typically auto-generated (see [`SpecCommand::usage`]) but can | |
| /// be manually set or overridden if needed. |
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## main #455 +/- ##
==========================================
- Coverage 47.66% 46.62% -1.04%
==========================================
Files 47 47
Lines 6928 7039 +111
Branches 6928 7039 +111
==========================================
- Hits 3302 3282 -20
- Misses 1780 1891 +111
- Partials 1846 1866 +20 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
Summary
Add comprehensive doc comments to the main public API types to improve discoverability and IDE support.
Changes
Each struct now includes:
Benefits
cargo docoutput🤖 Generated with Claude Code
Note
Enhances public API documentation for core CLI spec types without changing behavior.
cargo docoutput and IDE hover info across these structsWritten by Cursor Bugbot for commit 3aab606. This will update automatically on new commits. Configure here.