Misleading docs for an enum with struct variants

[mathstuf]

Given this structure:

pub enum OldTopicRemoval {
    Obsoleted {
        old_merge: StagedTopic,
        replacement: Option<StagedTopic>,
    },
    Removed(StagedTopic),
}

I'm seeing docs rendered as:

Which makes it look like Removed is more closely related to the fields of Obsoleted rather than on the same level. It'd be nice if the fields for the Obsoleted variant fields were either indented somehow or collapsed with the description.

[GuillaumeGomez]

A tricky one. The problem just gets bigger if it has more "sub-levels". The output shouldn't be based on indentation therefore. I'm more in favor for bigger margin between the struct fields and the other variants. Also, it would be nice to replace "Fields" by something like "Fields of Obsoleted variant".

[QuietMisdreavus]

I just took a moment to try out a few variations that might work for this. They all assume that the "Fields" header will include the name of the variant being described, but beyond that take a couple different directions of how it gets laid out.

Option 1: Extra margin under the list of struct fields

This is the simplest option, as all it does is slap some extra padding underneath the listing of struct fields via CSS. It provides a visible separation from the list of struct fields and the next variant in the listing.

Option 2: Print struct variant fields after the list of variants

This one's my personal favorite, as it provides a clean separation between the variant listing and the struct-field listing, without depending on more subtle style changes. On the other hand, it has the potential to put too much distance between a variant and its fields if an enum is huge enough. That could be mitigated by adding links and anchors between these sections.

Option 3: Either of the above, but with borders around the field listing

The list of struct fields is printed in a <table>, so the sky's the limit as far as drawing borders is concerned. It becomes a pure-CSS solution at that point, too. I admit this preview image is a little janky, but it's definitely possible to make this option look nicer with a little more thought put into the CSS.

Thoughts? Opinions?

[GuillaumeGomez]

My favorite is the first, but the result isn't good enough yet. It might be interesting to be able to hide by default the sub-type content and add a "show variant field" button.

[mathstuf]

This is probably too complicated, but Option 2 could have the following tweaks as well: for every subfield named the same, group them together (they're usually related anyways) and then list the variants it is a part of.

enum Animal {
    Cat { name: String, lives: u8, },
    Dog { name: String, breed: String, },
}

could render the name subfields together mentioning that it is part of both Cat and Dog while lives, and breed say they are only part of Cat and Dog, respectively. Rustdoc would probably need some directive/syntax for saying that a subfield's docstring should be shared though.

[QuietMisdreavus]

@GuillaumeGomez I've changed my mind, this looks a lot nicer.

Option 4: Wrap struct variant field listings in an auto-hidden block

When you initially load the page, there's a line under variants with struct fields letting you know you can click to expand the listing.

If you click to expand, the header and table unfold into a nicely-indented listing. The indentation and table borders fell into place with its presence in this folding block, and I really like how it looks.

If you want to take a look in your own browser and screen size, I've got this version hosted on my server.

[GuillaumeGomez]