cutedogs 🐕

A simple procedural macro for generating comprehensive Rust documentation with minimal boilerplate.

Installation

Add to your Cargo.toml:

[dependencies]
cutedogs = "0.0.1"

Usage

use cutedogs::document;

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

Features

Basic Documentation

#[document(
    summary = "Calculates the area of a rectangle",
    returns = "The area as a f64"
)]
fn area(width: f64, height: f64) -> f64 {
    width * height
}

Parameters

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

Examples

#[document(
    summary = "Divides two numbers",
    example = "let result = divide(10.0, 2.0);\nassert_eq!(result, 5.0);"
)]
fn divide(a: f64, b: f64) -> f64 {
    a / b
}

Unimplemented Functions

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

#[document(unimplemented = "Database integration not ready")]
fn connect_db() -> Result<(), String> {
    unimplemented!()
}

Advanced Features

#[document(
    summary = "Advanced function with all features",
    params = {"data": "Input data to process"},
    returns = "Processed result",
    example = "let result = advanced_fn(vec![1, 2, 3]);",
    panics = "Panics if input is empty",
    safety = "Safe to use with any input",
    since = "1.0.0",
    see_also = "helper_fn, another_fn",
    note = "This function is experimental"
)]
fn advanced_fn(data: Vec<i32>) -> Vec<i32> {
    data.into_iter().map(|x| x * 2).collect()
}

Deprecation

#[document(
    summary = "Old function",
    deprecated = "Use new_function() instead",
    deprecated_since = "2.0.0"
)]
fn old_function() {}

All Available Fields

License

MIT OR Apache-2.0