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

Question

你如何在类型之前的一个文档块中记录一个 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,
};

Answer 1

这就是我现在所做的，这真的很糟糕。

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

我想要的是我会用 Doxygen 编写的样式，它干净且易于阅读：

我再次猜想美丽在旁观者的眼中，因为我认为这看起来像是着火的垃圾，但 AFAIK rustdoc 不支持这一点（文档注释只是扩展名有限的常见标记），所以你可以：

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

• 使用类似函数的宏和#[doc]在结构上方的宏中定义你的东西，然后使用#[doc]属性来链接它们，我认为你不能只是#[doc = A_CONST]

  如何将 Rust 宏变量嵌入到文档中？ 以及如何将文字字符串与 const 字符串连接起来？ 也可能对此有用

Answer 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.
}

doxygen 1.9.2 的结果：

请注意评论中的讨论：给定的示例在 doxygen 中有效，但在cargo doc中无效。 Doxygen 不支持 Rust，因此代码首先必须被翻译成 doxygen 可以理解的东西（例如，通过 doxygen 过滤器）。 问题中的给定示例看起来与 C / C++ 代码非常相似。