documentation

Documentation Standards

Comprehensive guidelines for writing clear, maintainable, and useful documentation.

When to Use

Use this skill when:

• Writing README files
• Creating API documentation
• Writing user guides
• Documenting architecture decisions
• Creating inline code documentation
• Writing changelogs and release notes

Documentation Types

1. Code Documentation (Inline)

Purpose: Explain how code works to developers

Rust Documentation

/// Calculates the total price for a list of items.
///
/// # Arguments
///
/// * `items` - A slice of items to calculate the total for
///
/// # Returns
///
/// The total price as a floating-point number
///
/// # Examples
///
/// ```
/// let items = vec![
///     Item { name: "Widget", price: 10.0 },
///     Item { name: "Gadget", price: 20.0 },
/// ];
/// assert_eq!(calculate_total(&items), 30.0);
/// ```
///
/// # Panics
///
/// Panics if any item has a negative price.
pub fn calculate_total(items: &[Item]) -> f64 {
    items.iter().map(|item| item.price).sum()
}

/// User entity representing a system user.
///
/// This struct stores basic user information and provides
/// methods for user management.
///
/// # Examples
///
/// ```
/// let user = User::new("[email protected]", "John Doe");
/// println!("User: {}", user.name);
/// ```
#[derive(Debug, Clone)]
pub struct User {
    /// User's email address (unique identifier)
    pub email: String,
    /// User's display name
    pub name: String,
    /// Account creation timestamp
    pub created_at: DateTime<Utc>,
}

// Module documentation
//! # My Crate
//!
//! `my_crate` is a collection of utilities for doing X, Y, and Z.
//!
//! ## Features
//!
//! - Feature A
//! - Feature B
//!
//! ## Quick Start
//!
//! ```rust
//! use my_crate::do_something;
//! do_something();
//! ```

TypeScript/JavaScript Documentation

/**
 * Parses a configuration file and returns a validated config object.
 *
 * @param filePath - Path to the configuration file
 * @param options - Optional parsing options
 * @returns Promise resolving to the parsed configuration
 * @throws {ConfigError} If the file cannot be read or parsed
 *
 * @example
 * ```typescript
 * const config = await parseConfig('./config.toml');
 * console.log(config.database.url);
 * ```
 */
export async function parseConfig(
  filePath: string,
  options?: ParseOptions
): Promise<Config> {
  // Implementation
}

/**
 * User role enum defining permission levels.
 */
export enum UserRole {
  /** Can view content */
  Viewer = 'viewer',
  /** Can edit content */
  Editor = 'editor',
  /** Full access to all features */
  Admin = 'admin',
}

/**
 * Configuration options for the API client.
 *
 * @example
 * ```typescript
 * const options: ApiClientOptions = {
 *   baseUrl: 'https://api.example.com',
 *   timeout: 5000,
 *   retries: 3,
 * };
 * ```
 */
export interface ApiClientOptions {
  /** Base URL for API requests */
  baseUrl: string;
  /** Request timeout in milliseconds */
  timeout?: number;
  /** Number of retry attempts for failed requests */
  retries?: number;
}