在rustdoc中重复段落的惯用方法

juud5qan  于 2022-11-03  发布在  其他
关注(0)|答案(1)|浏览(117)

我终于花了一些时间来正确地记录我的第一个Rust库,我希望我的文档尽可能地符合习惯。(为了简单起见,我将它们称为AlphaBeta),它们以稍微不同的方式表示相同的数据,针对不同的用途进行了优化。差异是微妙的,但很重要,我想使它尽可能为我的最终用户所理解。
所以当我开始做文档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中没有“从外部文件导入文档段落”命令,对吧?

jhkqcmku

jhkqcmku1#

我会避免重复文档,这样读者就不必把同一个文本读两遍,可能会想“它是一样的吗?”。为了仍然记录这两个文档,你可以只从一个项目的文档引用到其他文档,节省阅读时间,仍然记录所有内容。
如果你仍然想复制完全相同的文本两次,你可以把它放在一个单独的文件shared.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` is a `struct` doing so and so.
///
#[doc = include_str!("shared.md")]
struct Alpha {
   // ...
}
/// `Beta` is a `struct` doing so and so.
///
#[doc = include_str!("shared.md")]
struct Beta {
   // ...
}

正如乔纳斯·法斯宾德所说

相关问题