Code Documentation Skill

Creates and reviews documentation embedded directly in source code, including doc comments, API documentation, and inline comments.

When to Use

Use this skill when:

• •Writing documentation comments for functions, types, or modules
• •Adding examples to code documentation
• •Reviewing code documentation quality
• •Creating API reference documentation
• •Adding inline comments to explain complex logic

Documentation Types

1. API Documentation (Doc Comments)

Documentation for public interfaces that appears in generated docs.

Purpose: Describe what code does, how to use it, and what to expect.

Characteristics:

• •Rendered into HTML documentation
• •Often includes runnable examples
• •Follows language-specific conventions

2. Inline Comments

Comments within code explaining implementation details.

Purpose: Explain why code works a certain way, not what it does.

Characteristics:

• •Not rendered in external docs
• •Explains non-obvious decisions
• •Documents workarounds or edge cases

Instructions

Step 1: Load Language-Specific Guidelines

Based on the programming language, load the appropriate documentation guide:

Step 2: Apply Documentation Quality Standards

Load and follow:

• •.aiassisted/guidelines/documentation/documentation-quality-standards.md

Key requirements:

• •No hyperbolic language
• •No marketing speak
• •Technical accuracy over promotional claims
• •State facts, not opinions

Step 3: Document Public Items

Every public item needs documentation covering:

Required Sections

Documentation Template

[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]

Step 4: Write Quality Examples

Examples must be:

• •Complete: Can be copied and run
• •Focused: Demonstrate one concept
• •Realistic: Show actual use cases
• •Tested: Verified to compile and run

Example Guidelines

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

Step 5: Write Effective Inline Comments

For inline comments:

Do Comment:

• •Non-obvious algorithms or logic
• •Workarounds for bugs or limitations
• •Business rules encoded in code
• •Performance-critical sections
• •Security-sensitive code

Don't Comment:

• •What the code literally does (code is self-documenting)
• •Obvious operations
• •Every line or block
• •Redundant information

Inline Comment Examples

// 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() { ... }

Step 6: Review Documentation

When reviewing documentation:

Check for Completeness

• • All public items documented
• • Examples present and working
• • Error conditions documented
• • Panic conditions documented
• • Safety requirements documented

Check for Quality

• • Summary is one sentence
• • No hyperbolic language
• • Technical accuracy
• • Examples are runnable
• • Links are valid

Check for Style

• • Consistent formatting
• • Line length under 100 chars
• • Proper grammar and spelling
• • Follows language conventions

Language-Specific Guidance

Rust

/// 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> { ... }

General (Other Languages)

Apply these principles regardless of language:

1. •First line is summary - stands alone in listings
2. •Examples before edge cases - show typical usage first
3. •Link to related items - connect related functionality
4. •State facts, not opinions - avoid "better", "best", "powerful"

Common Documentation Patterns

Constructor/Factory Functions

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.

Configuration Types

Summary: Configuration for X.

Description: What this configures, default behavior.

Field docs: Each field documented individually.

Examples: Show common configuration patterns.

Trait/Interface Types

Summary: Defines behavior for X.

Description: When to implement, what it provides.

Method docs: Each method documented with contract.

Examples: Show implementation example.

Error Types

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.

Quality Checklist

Before completing documentation:

• • Summary is clear and under 80 characters
• • All public items have documentation
• • Examples compile and run correctly
• • Error conditions are documented
• • No forbidden terminology (see quality standards)
• • Links to related items work
• • Grammar and spelling are correct
• • Consistent formatting throughout

References

• •.aiassisted/guidelines/documentation/documentation-quality-standards.md
• •.aiassisted/guidelines/rust/rust-documentation-guide.md (for Rust)
• •Write the Docs Guide