如何在Rust文档中定义可复用的全局或文件级链接？

Rust的文档注释本身没有原生支持全局跨项的链接定义，但有几种简便方法可以实现同一文件或跨文件的链接复用：

1. 文件内复用：文件级注释定义链接 #

在文件顶部用//!开头的文件级文档注释里定义链接，同一文件内的所有项都能直接复用这些链接标记：

//! [documentation]: https://www.rust-lang.org/learn
//! [rust-book]: https://doc.rust-lang.org/book/

/// 这里可以直接引用[documentation]链接
pub fn foo() {}

/// 这里也能复用[rust-book]链接
pub fn bar() {}

这种方式是最直接的，适合单个文件内的链接复用需求。

2. 跨文件复用：用宏封装链接定义 #

如果需要在多个文件里复用同一组链接，可以把链接定义封装成宏，在每个需要的项的文档注释里调用：

macro_rules! common_doc_links {
    () => {
        /// [documentation]: https://www.rust-lang.org/learn
        /// [rust-book]: https://doc.rust-lang.org/book/
    };
}

/// 这是foo函数的文档说明
///
common_doc_links!();
pub fn foo() {}

/// 这是bar函数的文档说明
///
common_doc_links!();
pub fn bar() {}

宏会在编译时把链接定义展开到每个项的文档里，虽然底层是重复展开，但使用时不需要重复写链接内容。

3. 简洁跨文件复用：#[doc = ...]属性拼接 #

可以把共享链接定义成常量字符串，再通过#[doc = ...]属性将其拼接到项的文档中：

const COMMON_LINKS: &str = "\n[documentation]: https://www.rust-lang.org/learn\n[rust-book]: https://doc.rust-lang.org/book/";

#[doc = "这是foo函数的文档" COMMON_LINKS]
pub fn foo() {}

#[doc = "这是bar函数的文档" COMMON_LINKS]
pub fn bar() {}

这种方式更简洁，生成的文档也不会冗余显示重复的链接定义。

需要注意的是，目前Rust还没有支持跨crate的全局链接定义方案，上述方法都是在 crate 内部实现复用的可行途径。

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