Rust宏文档化工具documented-macros的使用指南

工具简介

documented-macros是一个专门为Rust宏设计的文档化工具库，旨在简化宏代码的文档生成和维护过程。它提供了一套简洁的API和过程宏，帮助开发者自动生成符合Rustdoc标准的宏文档，同时保持文档与代码的同步。

主要特性

• 自动生成标准化的宏文档模板
• 支持内联文档注释和外部文档链接
• 提供宏参数和用法的结构化描述
• 与cargo doc无缝集成
• 支持文档测试（doctest）生成

安装方法

在Cargo.toml中添加依赖：

[dependencies]
documented-macros = "0.3"

基本使用方法

1. 基础文档化

use documented_macros::documented;

#[documented]
/// 这是一个简单的加法宏
///
/// # 示例
/// ```
/// let result = add!(2, 3);
/// assert_eq!(result, 5);
/// ```
macro_rules! add {
    ($a:expr, $b:expr) => {
        $a + $b
    };
}

2. 带参数的详细文档

#[documented]
/// 条件执行宏
///
/// # 参数
/// - `cond`: 布尔条件表达式
/// - `then_block`: 条件为真时执行的代码块
/// - `else_block`: 条件为假时执行的代码块（可选）
///
/// # 示例
/// ```
/// let x = 5;
/// when!(x > 0 => {
///     println!("x是正数");
/// } else {
///     println!("x不是正数");
/// });
/// ```
macro_rules! when {
    ($cond:expr => $then_block:block else $else_block:block) => {
        if $cond { $then_block } else { $else_block }
    };
    ($cond:expr => $then_block:block) => {
        if $cond { $then_block }
    };
}

3. 复杂宏的文档组织

#[documented]
/// 数据结构生成宏
///
/// 这个宏可以生成带有指定字段的结构体及其实现
///
/// # 语法
/// ```ignore
/// make_struct! {
///     #[derive(Debug, Clone)]
///     struct MyStruct {
///         field1: Type1,
///         field2: Type2,
///         // ... 更多字段
///     }
/// }
/// ```
macro_rules! make_struct {
    // 宏实现代码...
}

高级功能

文档测试验证

#[documented]
/// 向量操作宏
///
/// # 示例
/// ```
/// let v = vec![1, 2, 3];
/// let doubled = vec_map!(v, |x| x * 2);
/// assert_eq!(doubled, vec![2, 4, 6]);
/// ```
macro_rules! vec_map {
    ($vec:expr, $func:expr) => {
        $vec.into_iter().map($func).collect()
    };
}

跨文件文档链接

#[documented]
/// 日志记录宏
///
/// 更多详细信息参见[日志模块文档](../log_module/index.html)
///
/// # 注意
/// 需要先初始化日志系统
macro_rules! log {
    ($level:expr, $($arg:tt)*) => {
        // 实现代码
    };
}

最佳实践建议

1. 保持文档简洁：专注于说明宏的用途和用法
2. 提供完整示例：包含导入语句和使用场景
3. 描述所有参数：详细说明每个参数的类型和用途
4. 包含错误情况：说明宏可能失败的情况
5. 定期更新文档：确保文档与代码实现保持一致

查看生成的文档

运行以下命令查看生成的文档：

cargo doc --open

生成的文档将包含所有使用#[documented]属性标记的宏的完整文档，包括示例代码和参数说明。

这个工具特别适合大型项目中的宏开发，能够显著提高宏代码的可维护性和可读性。

完整示例demo

// 引入documented-macros库
use documented_macros::documented;

// 基础文档化示例
#[documented]
/// 这是一个简单的加法宏
///
/// # 示例
/// ```
/// let result = add!(2, 3);
/// assert_eq!(result, 5);
/// ```
macro_rules! add {
    ($a:expr, $b:expr) => {
        $a + $b
    };
}

// 带参数的详细文档示例
#[documented]
/// 条件执行宏
///
/// # 参数
/// - `cond`: 布尔条件表达式
/// - `then_block`: 条件为真时执行的代码块
/// - `else_block`: 条件为假时执行的代码块（可选）
///
/// # 示例
/// ```
/// let x = 5;
/// when!(x > 0 => {
///     println!("x是正数");
/// } else {
///     println!("x不是正数");
/// });
/// ```
macro_rules! when {
    ($cond:expr => $then_block:block else $else_block:block) => {
        if $cond { $then_block } else { $else_block }
    };
    ($cond:expr => $then_block:block) => {
        if $cond { $then_block }
    };
}

// 复杂宏的文档组织示例
#[documented]
/// 数据结构生成宏
///
/// 这个宏可以生成带有指定字段的结构体及其实现
///
/// # 语法
/// ```ignore
/// make_struct! {
///     #[derive(Debug, Clone)]
///     struct MyStruct {
///         field1: Type1,
///         field2: Type2,
///         // ... 更多字段
///     }
/// }
/// ```
macro_rules! make_struct {
    // 宏实现代码...
}

// 文档测试验证示例
#[documented]
/// 向量操作宏
///
/// # 示例
/// ```
/// let v = vec![1, 2, 3];
/// let doubled = vec_map!(v, |x| x * 2);
/// assert_eq!(doubled, vec![2, 4, 6]);
/// ```
macro_rules! vec_map {
    ($vec:expr, $func:expr) => {
        $vec.into_iter().map($func).collect()
    };
}

// 跨文件文档链接示例
#[documented]
/// 日志记录宏
///
/// 更多详细信息参见[日志模块文档](../log_module/index.html)
///
/// # 注意
/// 需要先初始化日志系统
macro_rules! log {
    ($level:expr, $($arg:tt)*) => {
        // 实现代码
    };
}

fn main() {
    // 使用加法宏
    let result = add!(2, 3);
    println!("2 + 3 = {}", result);
    
    // 使用条件执行宏
    let x = 5;
    when!(x > 0 => {
        println!("x是正数");
    } else {
        println!("x不是正数");
    });
    
    // 使用向量操作宏
    let v = vec![1, 2, 3];
    let doubled = vec_map!(v, |x| x * 2);
    println!("向量加倍结果: {:?}", doubled);
}