Smithery is now a part of Arcade.dev! Read more in our announcement here
Creates and reviews documentation embedded in source code including doc comments, API documentation, and inline documentation...
Creates and reviews documentation embedded directly in source code, including doc comments, API documentation, and inline comments.
Use this skill when:
Documentation for public interfaces that appears in generated docs.
Purpose: Describe what code does, how to use it, and what to expect.
Characteristics:
Comments within code explaining implementation details.
Purpose: Explain why code works a certain way, not what it does.
Characteristics:
Based on the programming language, load the appropriate documentation guide:
| Language | Guideline File |
|---|---|
| Rust | .aiassisted/guidelines/rust/rust-documentation-guide.md |
| Other | Apply general principles below |
Load and follow:
.aiassisted/guidelines/documentation/documentation-quality-standards.mdKey requirements:
Every public item needs documentation covering:
| Section | When Required |
|---|---|
| Summary | Always - first line, one sentence |
| Description | When behavior needs explanation |
| Examples | Always for public APIs |
| Errors | When function can fail |
| Panics | When function can panic |
| Safety | For unsafe code |
[One-line summary of what this does]
[Detailed description - what it does, when to use it, important behavior]
# Examples
[Working, copy-paste-ready examples]
# Errors
[What errors can occur and when]
# Panics
[Conditions that cause panics]
# Safety
[Safety requirements for unsafe code]
Examples must be:
Good example:
- Shows typical usage
- Handles errors appropriately
- Uses meaningful variable names
- Includes necessary imports
Bad example:
- Uses placeholder values ("foo", "bar")
- Ignores error handling
- Missing imports or context
- Demonstrates edge cases before basics
For inline comments:
Do Comment:
Don't Comment:
// Bad: Explains what (obvious)
// Add 1 to counter
counter += 1;
// Good: Explains why (non-obvious)
// Off-by-one adjustment: API returns 0-indexed positions but UI expects 1-indexed
counter += 1;
// Bad: Redundant with code
// Check if user is admin
if user.is_admin() { ... }
// Good: Documents business rule
// Only admins can delete archived records per compliance policy
if user.is_admin() { ... }
When reviewing documentation:
/// Creates a new configuration with default values.
///
/// This function initializes a `Config` struct with sensible defaults
/// suitable for most use cases. Use [`Config::builder`] for customization.
///
/// # Examples
///
/// ```rust
/// use my_crate::Config;
///
/// let config = Config::new();
/// assert_eq!(config.timeout, Duration::from_secs(30));
/// ```
///
/// # Errors
///
/// Returns [`ConfigError::MissingEnv`] if required environment variables
/// are not set.
pub fn new() -> Result<Config, ConfigError> { ... }
Apply these principles regardless of language:
Summary: Creates a new X with Y.
Description: Brief explanation of what gets created and initial state.
Examples: Show basic creation and common configurations.
Errors: What can go wrong during creation.
Summary: Configuration for X.
Description: What this configures, default behavior.
Field docs: Each field documented individually.
Examples: Show common configuration patterns.
Summary: Defines behavior for X.
Description: When to implement, what it provides.
Method docs: Each method documented with contract.
Examples: Show implementation example.
Summary: Errors that can occur during X.
Description: General error handling guidance.
Variant docs: Each variant with when it occurs.
Examples: Show error handling patterns.
Before completing documentation:
.aiassisted/guidelines/documentation/documentation-quality-standards.md.aiassisted/guidelines/rust/rust-documentation-guide.md (for Rust)