如何在Rustdoc中以惯用方式复用结构体说明段落？

针对你遇到的两个结构体Alpha和Beta文档差异说明同步问题，Rust社区有两种符合惯用风格的解决方式：

1. 用include_str!导入外部文档片段（推荐） #

rustdoc支持通过属性宏#[doc = include_str!()]直接导入外部文件内容，这是维护重复文档片段最可靠的方式：

步骤： #

• 创建单独的文档片段文件，比如docs/alpha_beta_diff.md，写入共享的差异说明：

# The difference between [`Alpha`]s and [`Beta`]s

While [`Alpha`]s do some important thing in this way, [`Beta`]s
do kind of the same important thing, but in this other way!

• 在Alpha和Beta的文档中引用这个文件：

/// [`Alpha`] is a `struct` doing so and so.
///
#[doc = include_str!("../docs/alpha_beta_diff.md")]
struct Alpha {
    // ...
}

/// [`Beta`] is a `struct` doing so and so.
///
#[doc = include_str!("../docs/alpha_beta_diff.md")]
struct Beta {
    // ...
}

后续只需修改alpha_beta_diff.md，两个结构体的文档就会自动同步，完全避免手动复制带来的不一致问题。

2. 文档交叉引用 #

如果不想维护外部文件，可以在其中一个结构体的文档中详细说明差异，另一个结构体的文档直接引导用户查看前者的对应章节：

/// [`Alpha`] is a `struct` doing so and so.
///
/// # The difference between [`Alpha`]s and [`Beta`]s
///
/// While [`Alpha`]s do some important thing in this way, [`Beta`]s
/// do kind of the same important thing, but in this other way!
struct Alpha {
    // ...
}

/// [`Beta`] is a `struct` doing so and so.
///
/// # The difference between [`Alpha`]s and [`Beta`]s
///
/// 关于二者的差异，请查看 [`Alpha`] 文档中的同名章节。
struct Beta {
    // ...
}

这种方式适合差异内容较长、不需要在两个地方重复显示的场景，但需要用户跳转查看。

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