cutedogs 🐕

Programmatic Rust documentation - Write docs like code, not comments.

cutedogs transforms function documentation from scattered comment blocks into structured, attribute-driven declarations. Instead of writing traditional doc comments, you define documentation as structured data using Rust attributes - making it type-safe, IDE-friendly, and programmatically verifiable.

Why cutedogs?

Traditional rustdoc (comment-based)

/// Calculates the area of a rectangle
/// 
/// # Parameters
/// * `width` - The width of the rectangle 
/// * `height` - The height of the rectangle
/// 
/// # Returns
/// The area as a f64
/// 
/// # Example
/// ```rust
/// let area = calculate_area(5.0, 3.0);
/// assert_eq!(area, 15.0);
/// ```
fn calculate_area(width: f64, height: f64) -> f64 {
    width * height
}

cutedogs (attribute-driven)

use cutedogs::document;

#[document(
    summary = "Calculates the area of a rectangle",
    params = {"width": "The width of the rectangle", "height": "The height of the rectangle"},
    returns = "The area as a f64",
    example = "let area = calculate_area(5.0, 3.0);\nassert_eq!(area, 15.0);"
)]
fn calculate_area(width: f64, height: f64) -> f64 {
    width * height
}

Key Benefits

✅ Structured & Type-Safe - Documentation fields are parsed at compile time
✅ IDE Support - Auto-completion, syntax highlighting, and refactoring tools work
✅ Programmatic - Generate docs from data, validate completeness, enforce standards
✅ Consistent - Uniform formatting and structure across your entire codebase
✅ Maintainable - Documentation is data, not prose scattered in comments

Installation

Add to your Cargo.toml:

[dependencies]
cutedogs = "0.0.5"

Quick Start

use cutedogs::document;

#[document(summary = "Adds two numbers together")]
fn add(a: i32, b: i32) -> i32 {
    a + b
}

This generates clean, formatted rustdoc output while keeping your documentation structured and maintainable.

Documentation Fields

Core Documentation

#[document(
    summary = "Processes user data and returns formatted output",
    params = {"name": "The user's full name", "age": "Age in years"},
    returns = "A formatted string containing user information"
)]
fn process_user(name: &str, age: u32) -> String {
    format!("{} is {} years old", name, age)
}

Examples & Testing

#[document(
    summary = "Divides two numbers with error handling",
    example = "let result = safe_divide(10.0, 2.0);\nassert_eq!(result, Ok(5.0));"
)]
fn safe_divide(a: f64, b: f64) -> Result<f64, String> {
    if b == 0.0 { Err("Division by zero".to_string()) } else { Ok(a / b) }
}

Unimplemented Functions

Mark functions as not yet implemented with clear messaging:

#[document(unimplemented)]
fn future_feature() -> String {
    unimplemented!()
}

#[document(unimplemented = "Waiting for database integration")]
fn connect_db() -> Result<(), String> {
    unimplemented!()
}

Advanced Documentation

#[document(
    summary = "Advanced data processing with comprehensive documentation",
    params = {"data": "Input vector to process"},
    returns = "Processed data with doubled values",
    example = "let result = process_data(vec![1, 2, 3]);",
    panics = "Panics if input vector is empty",
    safety = "Safe to use with any non-empty input",
    since = "1.0.0",
    see_also = "helper_function, related_processor",
    note = "This function is optimized for large datasets"
)]
fn process_data(data: Vec<i32>) -> Vec<i32> {
    assert!(!data.is_empty(), "Input cannot be empty");
    data.into_iter().map(|x| x * 2).collect()
}

Deprecation Management

#[document(
    summary = "Legacy function for backwards compatibility",
    deprecated = "Use new_process_function() instead for better performance",
    deprecated_since = "2.0.0"
)]
fn old_process_function() -> String {
    "legacy".to_string()
}

Complete Field Reference

Generated Output

cutedogs generates clean, properly formatted rustdoc comments that integrate seamlessly with cargo doc. The structured approach ensures consistent formatting, proper markdown sections, and complete documentation coverage.

Your IDE treats the attribute syntax as first-class Rust code, providing:

• Syntax highlighting
• Auto-completion
• Refactoring support
• Compile-time validation

License

MIT OR Apache-2.0