我终于花了一些时间来正确地记录我的第一个Rust库,我希望我的文档尽可能地符合习惯。(为了简单起见,我将它们称为Alpha
和Beta
),它们以稍微不同的方式表示相同的数据,针对不同的用途进行了优化。差异是微妙的,但很重要,我想使它尽可能为我的最终用户所理解。
所以当我开始做文档Alpha
时,我开始:
/// [`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
时,我感到复制粘贴的冲动:
/// [`Beta`] is a `struct` doing so and so.
///
/// # The difference between [`Alpha`]s and [`Beta`]s
///
/// The same exact text as in [`Alpha`]'s documentation!
struct Beta {
// ...
}
现在,我马上就能看到问题了,总有一天我会在Alpha
的文档中修改段落,忘记在Beta
的文档中修改它,瞧,我的文档不一致得令人不安。
所以我在想:解决这个问题最惯用的方法是什么?我想避免,例如,制作一个假的DifferenceBetweenAlphaAndBeta
空结构体只是为了把文档放在那里。通常的方法是什么?我估计rustdoc中没有“从外部文件导入文档段落”命令,对吧?
1条答案
按热度按时间jhkqcmku1#
我会避免重复文档,这样读者就不必把同一个文本读两遍,可能会想“它是一样的吗?”。为了仍然记录这两个文档,你可以只从一个项目的文档引用到其他文档,节省阅读时间,仍然记录所有内容。
如果你仍然想复制完全相同的文本两次,你可以把它放在一个单独的文件
shared.md
中:并将其包含在两个位置:
正如乔纳斯·法斯宾德所说