Rust子模块常量自动导出及文档整合方案问询

场景与现有实现 #

我有一个定义了trait的模块，其下包含多个子模块，这些子模块会随程序演进新增、修改或删除。每个子模块都定义了若干常量（即该子模块可接收的命令），我希望将这些常量整合到同一文档页面中，但仍在各自子模块文件中保留常量的实际定义。

目前我采用的实现方式是通过重导出所有常量，用通配符避免逐个罗列，并借助独立模块隔离命名空间：

a.rs #

pub(super) mod Cmds {
    /// Some doc
    pub const CMD_A1: &str = "CMD_A_1";

    /// More doc
    pub const CMD_A2: &str = "CMD_A_2";
}

// Actual implementation for A

b.rs #

pub(super) mod Cmds {
    pub const CMD_B1: &str = "CMD_B_1";
}

// Actual B code

Base.rs #

mod a;
mod b;

mod Cmds {
    pub use super::a::Cmds::*;
    pub use super::b::Cmds::*;   
}

这个方法能把所有常量整合到同一文档页面，但还需要实现以下特性：

1. 在常量列表中直接显示常量值，无需点击进入详情页
2. 避免常量值冲突（虽有前缀降低风险，但仍需保障）
3. 无需手动在pub use中罗列所有子模块
4. 尽量避免使用通配符（虽当前隔离无命名空间污染，但仍想规避）

解决方案 #

一、改用枚举（Enum）方案：多子模块共同贡献枚举成员 #

常量并非唯一选择，用枚举可以更优雅地实现命令的统一管理，同时天然避免值冲突，文档展示也更友好。

实现思路：

1. 在Base模块定义基础枚举，预留扩展能力；
2. 每个子模块通过宏向该枚举添加成员；
3. 利用派生宏让枚举自带值展示，文档中直接可见成员信息。

示例代码：

Base.rs

// 定义基础枚举，允许子模块扩展
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Command {
    #[doc(hidden)]
    __Placeholder,
}

// 定义宏让子模块添加枚举成员
#[macro_export]
macro_rules! add_command {
    ($variant:ident = $value:expr) => {
        impl From<$variant> for Command {
            fn from(_: $variant) -> Self {
                Command::$variant
            }
        }

        #[derive(Debug, Clone, Copy, PartialEq, Eq)]
        pub enum $variant { __Inner }

        impl $variant {
            pub const VALUE: &'static str = $value;
        }

        #[allow(non_camel_case_types)]
        impl Command {
            pub const $variant: Self = Command::$variant;
        }
    };
}

// 导入子模块
mod a;
mod b;

a.rs

use super::*;

// 添加A模块的命令
add_command!(CMD_A1 = "CMD_A_1");
add_command!(CMD_A2 = "CMD_A_2");

// Actual implementation for A

b.rs

use super::*;

add_command!(CMD_B1 = "CMD_B_1");

// Actual B code

这种方案的优势：

• 枚举成员天然唯一，彻底避免值冲突；
• 文档中通过VALUE常量或Debug实现直接展示命令值；
• 新增子模块只需调用宏，无需修改Base中的导入列表；
• 完全不用通配符，命名空间干净。

二、用宏自动收集子模块常量（保留常量方案） #

如果坚持使用常量，可以通过自定义宏自动扫描并导入所有子模块的Cmds模块，避免手动罗列和通配符。

实现思路：

1. 定义宏生成明确的pub use语句，替代通配符；
2. 用宏自动生成带值的文档注释，让常量值直接显示在文档列表中。

示例代码：

Base.rs

mod a;
mod b;

// 自定义宏生成明确的pub use语句
macro_rules! import_all_cmds {
    ($($module:ident),*) => {
        pub mod Cmds {
            $(pub use super::$module::Cmds::{CMD_$module1, CMD_$module2};)*
        }
    };
}

// 调用宏导入所有子模块的Cmds
import_all_cmds!(a, b);

优化常量文档显示值

在子模块中用宏生成带值的文档注释：

// 定义生成带值文档的宏
macro_rules! cmd_const {
    ($name:ident, $value:expr, $doc:expr) => {
        #[doc = $doc]
        #[doc = " 值: "]
        #[doc = $value]
        pub const $name: &str = $value;
    };
}

// a.rs中使用
pub(super) mod Cmds {
    use super::cmd_const;

    cmd_const!(CMD_A1, "CMD_A_1", "Some doc");
    cmd_const!(CMD_A2, "CMD_A_2", "More doc");
}

这样文档列表中会直接显示常量的值，无需点击详情页。

三、可选的Crate辅助 #

如果不想自己写宏，可以使用inventory crate自动收集子模块中的常量：

1. 在每个子模块的常量上标记#[inventory::collect]；
2. 在Base模块中通过inventory::iter遍历所有收集到的常量；
3. 结合文档宏让这些常量在统一页面展示。

这种方式完全自动化收集，无需手动维护子模块列表，但需要依赖第三方crate。

内容的提问来源于stack exchange，提问作者Sibear Jo