Rollup merge of #89506 - yaymukund:docblock-headings, r=GuillaumeGomez

librustdoc: Use correct heading levels.

Closes #89309

This fixes the `<h#>` header tags throughout the docs to reflect a semantic hierarchy.

- I ran a script to manually check that we don't have any files with multiple `<h1>` tags.
- Also checked that we never incorrectly nest e.g. a `<h2>` under an `<h3>`.
- I also spot-checked a bunch of pages (`trait.Read`, `enum.Ordering`, `primitive.isize`, `trait.Iterator`).

6 files changed, 37 insertions, 8 deletions

diff --git a/src/test/rustdoc/external-cross.rs b/src/test/rustdoc/external-cross.rs
index 056ed353462..3f8e1688291 100644
--- a/src/test/rustdoc/external-cross.rs
+++ b/src/test/rustdoc/external-cross.rs
@@ -6,5 +6,5 @@
 extern crate external_cross;
 
 // @has host/struct.NeedMoreDocs.html
-// @has - '//h1' 'Cross-crate imported docs'
+// @has - '//h2' 'Cross-crate imported docs'
 pub use external_cross::NeedMoreDocs;
diff --git a/src/test/rustdoc/external-doc.rs b/src/test/rustdoc/external-doc.rs
index fc29cb252e2..bd322d67a37 100644
--- a/src/test/rustdoc/external-doc.rs
+++ b/src/test/rustdoc/external-doc.rs
@@ -1,6 +1,6 @@
 // @has external_doc/struct.IncludeStrDocs.html
-// @has - '//h1' 'External Docs'
-// @has - '//h2' 'Inline Docs'
+// @has - '//h2' 'External Docs'
+// @has - '//h3' 'Inline Docs'
 #[doc = include_str!("auxiliary/external-doc.md")]
 /// ## Inline Docs
 pub struct IncludeStrDocs;
@@ -8,7 +8,7 @@ pub struct IncludeStrDocs;
 macro_rules! dir { () => { "auxiliary" } }
 
 // @has external_doc/struct.EagerExpansion.html
-// @has - '//h1' 'External Docs'
+// @has - '//h2' 'External Docs'
 #[doc = include_str!(concat!(dir!(), "/external-doc.md"))]
 /// ## Inline Docs
 pub struct EagerExpansion;
diff --git a/src/test/rustdoc/issue-42760.rs b/src/test/rustdoc/issue-42760.rs
index b07dc3f6e96..4944f815701 100644
--- a/src/test/rustdoc/issue-42760.rs
+++ b/src/test/rustdoc/issue-42760.rs
@@ -1,5 +1,5 @@
 // @has issue_42760/struct.NonGen.html
-// @has - '//h1' 'Example'
+// @has - '//h2' 'Example'
 
 /// Item docs.
 ///
diff --git a/src/test/rustdoc/issue-89309-heading-levels.rs b/src/test/rustdoc/issue-89309-heading-levels.rs
new file mode 100644
index 00000000000..bb706c28ffa
--- /dev/null
+++ b/src/test/rustdoc/issue-89309-heading-levels.rs
@@ -0,0 +1,29 @@
+#![crate_name = "foo"]
+
+// @has foo/trait.Read.html
+// @has - '//h2' 'Trait examples'
+/// # Trait examples
+pub trait Read {
+    // @has - '//h5' 'Function examples'
+    /// # Function examples
+    fn read(&mut self, buf: &mut [u8]) -> Result<usize, ()>;
+}
+
+pub struct Foo;
+
+// @has foo/struct.Foo.html
+impl Foo {
+    // @has - '//h5' 'Implementation header'
+    /// # Implementation header
+    pub fn bar(&self) -> usize {
+        1
+    }
+}
+
+impl Read for Foo {
+    // @has - '//h5' 'Trait implementation header'
+    /// # Trait implementation header
+    fn read(&mut self, buf: &mut [u8]) -> Result<usize, ()> {
+        Ok(1)
+    }
+}
diff --git a/src/test/rustdoc/short-docblock.rs b/src/test/rustdoc/short-docblock.rs
index 74fa783174d..17c44eab091 100644
--- a/src/test/rustdoc/short-docblock.rs
+++ b/src/test/rustdoc/short-docblock.rs
@@ -2,7 +2,7 @@
 
 // @has foo/index.html '//*[@class="item-right docblock-short"]/p' 'fooo'
 // @!has foo/index.html '//*[@class="item-right docblock-short"]/p/h1' 'fooo'
-// @has foo/fn.foo.html '//h1[@id="fooo"]/a[@href="#fooo"]' 'fooo'
+// @has foo/fn.foo.html '//h2[@id="fooo"]/a[@href="#fooo"]' 'fooo'
 
 /// # fooo
 ///
@@ -11,7 +11,7 @@ pub fn foo() {}
 
 // @has foo/index.html '//*[@class="item-right docblock-short"]/p' 'mooood'
 // @!has foo/index.html '//*[@class="item-right docblock-short"]/p/h2' 'mooood'
-// @has foo/foo/index.html '//h2[@id="mooood"]/a[@href="#mooood"]' 'mooood'
+// @has foo/foo/index.html '//h3[@id="mooood"]/a[@href="#mooood"]' 'mooood'
 
 /// ## mooood
 ///
diff --git a/src/test/rustdoc/smart-punct.rs b/src/test/rustdoc/smart-punct.rs
index 5319892c99c..7ae5bd69945 100644
--- a/src/test/rustdoc/smart-punct.rs
+++ b/src/test/rustdoc/smart-punct.rs
@@ -21,7 +21,7 @@
 //! ```
 
 // @has "foo/index.html" "//p" "This is the “start” of the ‘document’! How’d you know that “it’s” the start?"
-// @has "foo/index.html" "//h1" "Header with “smart punct’”"
+// @has "foo/index.html" "//h2" "Header with “smart punct’”"
 // @has "foo/index.html" '//a[@href="https://www.rust-lang.org"]' "link with “smart punct’” – yessiree!"
 // @has "foo/index.html" '//code' "this inline code -- it shouldn't have \"smart punct\""
 // @has "foo/index.html" '//pre' "let x = \"don't smart-punct me -- please!\";"