Headline Level in API Doc Comments

[killercup]

The API docs seem semantically quite nice, but don't incorporate headlines in comments into their document outline. The Vec doc e.g. uses an h1 for the title, h2 for "Methods", h3s for impl names and h4s for item names. Then a comment contains an h1 ("Examples") and the outline is ruined.

(This is a rustdoc issue, with probably low priority. It came up in #20826.)

One possibility to fix this is to switch to section and article tags as described by HTML5—currently, everything is a div. You can find some documentation here. Basically, this allows markup like the following to be meaningful:

main.content.struct
  h1 Struct std::vec::Vec
  pre.rust.struct ... code ...
  article.docblock
    h1 Examples
    // ...
  section.methods
    h1 Methods
    section.impl
      h1 impl‹T› Vec‹T›
      section.method
        h1 fn new() → Vec‹T›
        article.docblock
           p Constructs a new, empty Vec‹T›.
           h1 Examples
           // ...
      section.method
        h1 fn with_capacity(capacity: usize) → Vec‹T›
        article.docblock
           p Constructs a new, empty Vec‹T› with the specified capacity.
           h1 Examples
           // ...

(This syntax is Jade, it shows the outline quite niceley. I replaced some characters to prevent escaping.)

[steveklabnik]

Triage: this is still pretty messed up. See https://gsnedders.html5.org/outliner/process.py?url=http%3A%2F%2Fdoc.rust-lang.org%2Fstd%2Fvec%2F for example.

[steveklabnik]

@rust-lang/rustdoc do we ever plan on addressing this?

[killercup]

Wow, it's been two and a half years! Looking back at this, this still seems quite easily fixable by replacing a bunch of divs.

[GuillaumeGomez]

I'm afraid that the content "flow" would get out of hand: either we reduce sub-elements width or we remove the right side limit (which will end up in reducing sub-elements width in any case). Not really sure this is a good idea...

[killercup]

Huh? I don't follow, @GuillaumeGomez. This is about changing the markup, not the design?

[GuillaumeGomez]

You add indent for every new sub-item. The space limit will get reached very quickly, that's why I'm not sure this is a good idea for rustdoc.

[QuietMisdreavus]

Can't we change the style to make sub-items not add indent? This is a suggestion that should make no difference on the visual styling of the rendered HTML. Will replacing a <div> with a <section> cause that much of a problem?

[killercup]

@QuietMisdreavus Guillaume and I chatted about this in September after the comments above: https://discordapp.com/channels/442252698964721669/459149231702278154/494060795450097664

[camelid]

I think this has since been fixed. E.g., "Examples" in Vec::as_ptr is an h5. Please reopen if I misunderstood.