How do you document a Rust struct/enum in one documentation block before the struct?

Question

How do you document a Rust struct or enum in one documentation block before the type, so as to avoid polluting the contents with confusing mess?

This is what I do at the moment, which is really terrible.

/// 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,
}

What I want is the style I would write it in Doxygen, which is clean and easy to read:

/** \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

This is what I do at the moment, which is really terrible.

I guess the beauty is in the eye of the beholder? It looks fine to me, the reader of the code gets to see the documentation for the corresponding item in the same place, which makes sense.

What I want is the style I would write it in Doxygen, which is clean and easy to read:

Again I guess beauty is in the eye of the beholder as I think this looks like garbage on fire, but AFAIK rustdoc does not support this (a doc-comment is just commonmark with limited extension ), so you could:

• ignore rustdoc's support for sub-items entirely, just document everything however you want at the toplevel item

• use function-like macros and #[doc] to define your stuff in macros above the structure, then #[doc] attributes to link those, I don't think you can just #[doc = A_CONST]

  How to embed a Rust macro variable into documentation? and How to concatenate a literal string with a const string? could also be useful for that purpose

Answer 2

How about documenting the enum values after the enum values like:

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

Result with doxygen 1.9.2:

Note from the discussion in the comment: the given example works in doxygen but not in cargo doc . Doxygen does not support Rust so the code first has to be translated into something that doxygen does understand (eg by means of a doxygen filter). The given example in the question looks quite similar to C / C++ code.