Use # vs. ## consistently for headings in documentation

[huonw]

Some places use # Examples others use ## Examples:

#:

• rust/src/libstd/collections/hashmap.rs

  Line 692 in 4f120e6

  /// # Example

• rust/src/libstd/rand/mod.rs

  Line 23 in 4f120e6

  # Task-local RNG

• rust/src/libstd/io/mod.rs

  Line 24 in 4f120e6

  # Examples

##:

• rust/src/libcollections/slice.rs

  Line 26 in 4f120e6

  ## Structs

• rust/src/liballoc/rc.rs

  Line 26 in 4f120e6

  ## Examples

• rust/src/liballoc/lib.rs

  Line 24 in 4f120e6

  //! ## Owned pointers

It seems that single # is far more popular at the moment:

$ git grep ' # ' -- '*.rs' | wc -l
922
$ git grep ' ## ' -- '*.rs' | wc -l
62

cc @steveklabnik

[steveklabnik]

Yeah, I'm not sure how Rustdoc renders these two off the top of my head, but # is supposed to be an <h1>, with just one on the page. ## for <h2> makes more semantic sense to me.

[bluss]

Single # headings are so large they look out of place in method documentation (example)

[lilyball]

We could just fix the documentation styles to make <h1> look however we want.

[steveklabnik]

There's only supposed to be one H1 per section. H2 is more appropriate.

[lilyball]

@steveklabnik What do you mean "supposed to be"? Heading tags introduce sections. There are 6 levels of heading tags. There's no intrinsic semantic meaning to each level, except in that higher levels are considered to nest within lower ones (and typically use a smaller font, though you can certainly override that however you wish).

Given that we don't use a <h1> to introduce the documentation block, I don't see any problem with allowing the use of <h1> as the first level of section within the documentation block.

[steveklabnik]

Headings form a 'document outline,' and there's only supposed to be one h1 per page, although with HTML5 the outline resets per

, so you can have one per that as well.

https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements makes mention of this,for example.

This is, of course, a recommendation. But we should strive to act according to best practices where possible.

[lilyball]

My main objection is that I think

/// ## Example

is wrong if there was no preceding

/// # Foo

header. You're looking at the rustdoc HTML output, but that's basically embedding a tiny document within a bigger one. From the perspective of the docstring itself, # Example is not only more aesthetically pleasing, but it's also more correct, being the first level of headings.

If you care about the usage of <h1> vs <h2> in the rustdoc HTML output, perhaps rustdoc could actually modify the markdown output to increase all the headings by one level?

[steveklabnik]

I agree that in general, the HTML Rustdoc generates should get a once-over.

Why does it matter that this fragment has a single heading? In all contexts where it's used, there should be (emphasis on should there) be an h1 generated for the surrounding page. It's never the single top level heading.

And, when there's more than one heading, then it as h1 doesn't make sense either.

[steveklabnik]

I have a vague uneasiness about Rustdoc producing a h2 when I type #. Can't quantify it specifically...

[chris-morgan]

I’m not in the slightest bit uneasy about bumping the start level for headings. Doing that would be considered entirely normal in reStructuredText for things like Python docs, anyway. But then, reStructuredText is defined that way, that heading levels are purely a document-level construct, whereas strictly Markdown headings are defined as global constructs (this is not a good thing, and I feel entirely at liberty to ignore it).

(I don’t like the whole # thing much, anyway; I prefer the underlining technique, which Markdown supports also and which is the only way to do headings in reStructuredText.)

[lilyball]

@steveklabnik When using Markdown to generate an entire web page, you care about # becoming <h1>. But when using it to generate a fragment that's inserted into a web page, I think it's perfectly reasonable for the output to be mangled in whatever way the context wants it to be mangled. Heck, I'd have no objection if rustdoc wanted to map the # headings to some special <div> and ditch the header tags entirely.

[steveklabnik]

/cc @aturon