Can I document a struct in a comment block?

help
1

This is my very much preferred style of Doxycommenting a struct in C:

/** @struct Thingy
 *      Gadget that things the thing.
 *
 *  @var    Thingy::jobbler
 *      Doodad for the teaser.
 *
 *  @var    Thingy::wotsit
 *      Wot what wawt.
 */
struct Thingy
{
  unsigned      jobbler;
  struct Wotsit wotsit;
}

Can I do this with Rust documentation comments, rather than having to comment each member individually?

2

I’m not aware of any alternatives to putting the field’s documentation on the fields directly, i.e.

/// Gadget that things the thing.
pub struct Thingy {
    /// Doodad for the teaser.
    pub jobbler: usize,
    /// Wot what wawt.
    pub wotsit: Wotsit,
}

Since doc comments are visible to macros, it’s not impossible to write a macro that processes your favorite syntax, like

#[custom_doc_style]
/** @struct Thingy
 *      Gadget that things the thing.
 *
 *  @var    Thingy::jobbler
 *      Doodad for the teaser.
 *
 *  @var    Thingy::wotsit
 *      Wot what wawt.
 */
pub struct Thingy {
    pub jobbler: usize,
    pub wotsit: Wotsit,
}

could have custom_doc_style re-write the comments appropriately. But I’m not aware of anyone who did or would want to do something like that.

One great perk of a standardized tools like rustfmt or rustdoc is that people reading code can encounter a very consistent style throughout the ecosystem, so following “the same everyone else is doing” has advantages.

6 Likes
3

Thanks - I didn't know you could do anything like that with macros and I will certainly have a look at that.

I do believe in the benefits of consistency, but I think Rust is a bit heavy on established style and bit light on making that style easy to read. :slight_smile:

4

What's hard to read about rustdoc comments?

2 Likes
5

In my experience, something being “easy to read” is often surprisingly strongly related to how familiar one is with the syntax in question, so it may or may not be the case that with more exposure to Rust documentation in code, your perspective might change in the future.

Also note that Thingy::jobbler to refer to a field is very much not any standard syntax in Rust; this kind of syntax only works to refer to methods and associated functions (and also associated constants and types). I don’t know off the top of my head whether Thingy::jobbler has any meaning in C, so perhaps it’s analogous there anyways…

Also note that writing a procedural macro that does this is not very super easy, mostly because procedural macros in general aren’t super easy, and additionally you need to do parsing / manipulation of the strings in the doc comments, too. But if you’re motivated by this case, it may of course be a great way/project for learning more about procedural comments in the first place. As a starting point, in case you wonder how doc comments will appear in the abstract syntax tree, they get converted into #[doc = "contents…"] attributes by the compiler. In order to learn about procedural macros, I don’t know good tutorials off the top of my head, but using a tutorial and examples might certainly make it easier to learn than just inspecting the API and reference, and maybe APIs of important 3rd party crates. Of course, for a high-level overview, a look into the relevant page of the book can also be a good first step.

6

Even with the syntax highlighting of modern editors, I find it mentally tiring to switch line-by-line between comment and code. Particularly with structs (as opposed to enums), I would like to read the comment for the entire struct in one go.

I feel that the way one's brain processes the struct on one hand, and the comments for it on the other, are quite different, and it's bewildering to constantly switch.

As @steffahn has noted since I started this reply, it's possible to be more or less used to certain styles, but I don't think that this precludes some styles being objectively better than others. In a past life I worked as a newspaper subeditor, and visual style matters to me. You only need compare modern newspapers with those of the 19th century to realise how better design results in better comprehension.

My other Rust bugbear, for similar reason, is the convention of putting opening braces on the end of the line before the new environment. Most often I see people complaining that spaces are for humans and braces are for compilers, and that this practice is the next best thing to Python-style brace-free code. The original argument is bad though; braces are for compilers, but they are also for humans.

Anyway, it's not the end of the world - I just wish Rust would be a bit less prescriptive on some of these things. Some people really struggle with reading dense but irregular text.

7

FYI, even though I personally don’t like that style, note that there is an (unstable, but thus usable with nightly) option for rustfmt to configure this.

8

Note that Rustdoc already accepts it to link to fields.

2 Likes
9

well, then… you never stop learning new things ^^

10

It's not "bewildering" after a few weeks of getting used to it.

1 Like
11

One thing that might help is to configure your editor's syntax coloring (or pick a theme) such that the doc comments between the fields/params are subdued, or at least contrast with the fields/params. That way your eyes can scan over the fields/params (ignoring the doc comments) more easily.

I sympathize because I think the triple-slash comments look busy and they're jammed up against the code/definitions. In fact I use the old style doc comments (/**) for that reason, although I can't recommend it because I'm probably the only one here who does that. You do have to get used to the standard commenting style, since you have to read other people's code of course.

1 Like