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

Consider giving your eyes a chance to adjust to the style you see as "really terrible" at the moment. I suspect it won't look so terrible after just a couple of weeks. — user4815162342, Aug 21 '21 at 12:56
Apart from the opinion-based question of which looks better, one big drawback of the second style is that you need to repeat the enum names in the comment, with the added risks that they will go out of sync with the code if someone changes the code and forgets to update the comment. — Jmb, Aug 21 '21 at 16:44

score 3 · Answer 1 · answered Aug 21 '21 at 13:09

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

albert · Answer 2 · 2022-06-28T08:01:55.170

1

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 (e.g. by means of a doxygen filter). The given example in the question looks quite similar to C / C++ code.

edited Jun 28 '22 at 08:01

answered Dec 14 '21 at 12:01

albert

8,285
3
19
32

Sorry, but that is really terrible advice, since you document the wrong thing... Meaning `EnumValueTheSecond` will get the documentation of the first line etc.! – enaut Jun 26 '22 at 05:41
@enaut this is in my opinion not true Which version of doxygen are you using? I just added the result I get when I use the code in my answer with the doxygen version that was current at the moment of the answer (i.e. 1.9.2) the current doxygen version is 1.9.4. – albert Jun 26 '22 at 17:08
1

oh I see… – but if using `cargo doc` which is used a lot with rust you will document the wrong enum variations. You should probably add a "works only with doxygen" disclaimer. – enaut Jun 27 '22 at 19:28
@enaut thanks. The code looked like C++ code (I don't know Rust and Rust is not supported by doxygen), the sentence that made me give the examole was "What I want is the style I would write it in Doxygen, which is clean and easy to read:" so I showed another doxygen possibility. Somewheer I might have assumed as well that the user first translated through a doxygen filter the Rust coode into something understandable by doxygen. – albert Jun 28 '22 at 07:58
this is wrong rust – David 天宇 Wong Nov 30 '22 at 04:52

score 0 · Answer 3 · answered Mar 18 '23 at 04:26

It wont do what you asked, but may be more aesthetically pleasing:

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

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

3 Answers3