你如何在结构之前的一个文档块中记录一个 Rust 结构/枚举？

Posted 2023-02-18

【中文标题】你如何在结构之前的一个文档块中记录一个 Rust 结构/枚举？

【英文标题】：How do you document a Rust struct/enum in one documentation block before the struct?

【发布时间】：2021-10-22 14:29:19

【问题描述】：

你如何在类型之前的一个文档块中记录一个 Rust 结构或枚举，以避免混淆混乱污染内容？

这就是我目前所做的，这真的很糟糕。

/// Enumerates the possible jobblers in thingy paradigm.
enum MyEnum

  /// Something is a blue exchange doodad thingy thing. 
  EnumValue1,
  /// Something is meld mould mild mote.
  EnumValueTheSecond,
  /// Vivamus arcu mauris, interdum nec ultricies vitae, sagittis sit.
  EnumValueGamma,

我想要的是我会用 Doxygen 编写的风格，简洁易读：

/** \enum MyEnum
 *     Enumerates the possible jobblers in thingy paradigm.
 *  \var  MyEnum::EnumValue1
 *     Something is a blue exchange doodad thingy thing. 
 *  \var  MyEnum::EnumValueTheSecond
 *     Something is meld mould mild mote.
 *  \var  MyEnum::EnumValueGamma
 *     Vivamus arcu mauris, interdum nec ultricies vitae, sagittis sit.
 */
enum MyEnum

  EnumValue1,
  EnumValueTheSecond,
  EnumValueGamma,
;

【问题讨论】：

考虑让您的眼睛有机会适应您目前认为“非常糟糕”的风格。我怀疑几周后它看起来不会那么糟糕。

除了看起来更好的基于意见的问题之外，第二种样式的一个大缺点是您需要在评论中重复枚举名称，增加了它们会消失的风险如果有人更改代码并忘记更新评论，则与代码同步。

【参考方案1】：

这就是我目前所做的，这真的很糟糕。

我猜美丽在旁观者的眼中？对我来说看起来不错，代码的读者可以在同一个地方看到相应项目的文档，这是有道理的。

我想要的是我会用 Doxygen 编写的风格，简洁易读：

我再次猜想美丽在旁观者的眼中，因为我认为这看起来像是着火的垃圾，但 AFAIK rustdoc 不支持这一点（文档评论只是 commonmark with limited extension），所以你可以：

完全忽略 rustdoc 对子项目的支持，只需在顶层项目中记录您想要的所有内容

use function-like macros and #[doc] 在结构上方的宏中定义你的东西，然后用#[doc] 属性来链接这些，我认为你不能只是#[doc = A_CONST]

How to embed a Rust macro variable into documentation? 和 How to concatenate a literal string with a const string? 也可以用于此目的

【参考方案2】：

如何在枚举值之后记录枚举值，例如：

/// Enumerates the possible jobblers in thingy paradigm.
enum MyEnum

  EnumValue1, ///< Something is a blue exchange doodad thingy thing.
  EnumValueTheSecond, ///< Something is meld mould mild mote.
  EnumValueGamma, ///< Vivamus arcu mauris, interdum nec ultricies vitae, sagittis sit.