Rust编写文档时能否引用const常量值实现字符串插值效果？

核心结论 #

原生稳定版Rust不支持在///开头的普通文档注释里直接用${常量名}这类语法自动引用替换const常量的取值，普通文档注释的内容会被直接当做静态Markdown文本渲染，不会自动解析代码里的常量做插值替换。

可行实现方式 #

1. 零依赖原生实现 #

如果不想引入第三方crate，可以通过声明式宏把常量定义和文档生成绑定到一起，避免手动重复写值导致后续修改不同步，示例代码：

macro_rules! define_expiring_struct {
    ($expire_minutes:expr) => {
        /// A struct that does something
        /// Whatever this struct does, it expires in
        #[doc = stringify!($expire_minutes)]
        /// minutes.
        pub struct SomeStruct;

        /// 过期时间常量，单位为分钟
        pub const EXPIRATION_TIME_IN_MINUTES: i64 = $expire_minutes;
    }
}

// 统一在这里修改数值，文档和常量会同步更新
define_expiring_struct!(60 * 24);

这个写法的缺点是文档里展示的是传入的表达式60 * 24，而非计算后的最终值1440，如果需要直接展示计算后的常量值，需要用支持const字符串拼接的工具库。

2. 第三方库实现（推荐用于需要展示常量计算值的场景） #

使用支持const环境字符串拼接的工具库提供的对应宏，可以在编译期把常量的实际计算值转成字符串，直接拼接到文档属性中，实现真正的自动取值插值，示例：

use const_format::concatcp;

const EXPIRATION_TIME_IN_MINUTES: i64 = 60 * 24;

#[doc = concatcp!(
    "A struct that does something\n",
    "Whatever this struct does, it expires in ",
    EXPIRATION_TIME_IN_MINUTES,
    " minutes."
)]
struct SomeStruct {
    // 结构体字段定义
}

用这个写法修改EXPIRATION_TIME_IN_MINUTES的取值时，文档里的对应数值会自动同步更新，完全不需要手动修改文档内容，非常适合标注默认配置值、超时时间这类需要和代码常量保持一致的文档场景。

补充说明 #

• 所有通过#[doc = "xxx"]属性写入的文档内容，和/// xxx写法的文档注释渲染效果完全一致，没有任何展示差异。
• Rust nightly版本提供了部分未稳定的文档相关特性，可以实现更灵活的插值逻辑，但未稳定特性可能随时变更，不建议在生产环境使用。

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