Closed
Description
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.)