Rollup merge of #117869 - GuillaumeGomez:comment-highlighting-item-decl, r=notriddle

[rustdoc] Add highlighting for comments in items declaration

Fixes #117555.

So after the discussion in https://github.com/rust-lang/rust/pull/117643, the outcome was that having the comments in the item declaration at the same level (in term of color) as the rest of the code was actually a bit distracting and could be improved.

The current highlighting color for comments is "lighter" than the rest and I think it fits perfectly to improve the current situation. With this, we now have different "levels" which makes it easier to read and filter out what we want when reading the items declaration.

Here's a screenshot:

![image](https://github.com/rust-lang/rust/assets/3050060/dbd98029-e98b-4997-9a89-6b823eaac9a4)

r? `@notriddle`

10 files changed, 123 insertions, 6 deletions

diff --git a/tests/rustdoc-gui/item-decl-comment-highlighting.goml b/tests/rustdoc-gui/item-decl-comment-highlighting.goml
new file mode 100644
index 00000000000..60772693d6c
--- /dev/null
+++ b/tests/rustdoc-gui/item-decl-comment-highlighting.goml
@@ -0,0 +1,73 @@
+// This test checks that comments in item declarations are highlighted.
+go-to: "file://" + |DOC_PATH| + "/test_docs/private/enum.Enum.html"
+show-text: true
+
+define-function: (
+    "check-item-decl-comment",
+    (theme, url, comment_color),
+    block {
+        go-to: |url|
+        set-local-storage: {"rustdoc-theme": |theme|, "rustdoc-use-system-theme": "false"}
+        reload:
+        assert-css: (".item-decl .comment", {"color": |comment_color|}, ALL)
+    }
+)
+
+define-function: (
+    "check-items-for-theme",
+    (theme, comment_color),
+    block {
+        call-function: ("check-item-decl-comment", {
+            "theme": |theme|,
+            "url": "file://" + |DOC_PATH| + "/test_docs/private/enum.Enum.html",
+            "comment_color": |comment_color|,
+        })
+        call-function: ("check-item-decl-comment", {
+            "theme": |theme|,
+            "url": "file://" + |DOC_PATH| + "/test_docs/private/struct.Struct.html",
+            "comment_color": |comment_color|,
+        })
+        call-function: ("check-item-decl-comment", {
+            "theme": |theme|,
+            "url": "file://" + |DOC_PATH| + "/test_docs/private/struct.Tuple.html",
+            "comment_color": |comment_color|,
+        })
+        call-function: ("check-item-decl-comment", {
+            "theme": |theme|,
+            "url": "file://" + |DOC_PATH| + "/test_docs/private/union.Union.html",
+            "comment_color": |comment_color|,
+        })
+        call-function: ("check-item-decl-comment", {
+            "theme": |theme|,
+            "url": "file://" + |DOC_PATH| + "/proc_macro_test/macro.make_answer.html",
+            "comment_color": |comment_color|,
+        })
+        call-function: ("check-item-decl-comment", {
+            "theme": |theme|,
+            "url": "file://" + |DOC_PATH| + "/proc_macro_test/derive.HelperAttr.html",
+            "comment_color": |comment_color|,
+        })
+    }
+)
+
+call-function: (
+    "check-items-for-theme",
+    {
+        "theme": "ayu",
+        "comment_color": "#788797",
+    }
+)
+call-function: (
+    "check-items-for-theme",
+    {
+        "theme": "dark",
+        "comment_color": "#8d8d8b",
+    }
+)
+call-function: (
+    "check-items-for-theme",
+    {
+        "theme": "light",
+        "comment_color": "#8e908c",
+    }
+)
diff --git a/tests/rustdoc-gui/sidebar-source-code.goml b/tests/rustdoc-gui/sidebar-source-code.goml
index 92b9045b734..0d72e670cf4 100644
--- a/tests/rustdoc-gui/sidebar-source-code.goml
+++ b/tests/rustdoc-gui/sidebar-source-code.goml
@@ -73,7 +73,7 @@ assert: "//*[@class='dir-entry' and @open]/*[text()='sub_mod']"
 // Only "another_folder" should be "open" in "lib2".
 assert: "//*[@class='dir-entry' and not(@open)]/*[text()='another_mod']"
 // All other trees should be collapsed.
-assert-count: ("//*[@id='src-sidebar']/details[not(text()='lib2') and not(@open)]", 10)
+assert-count: ("//*[@id='src-sidebar']/details[not(text()='lib2') and not(@open)]", 11)
 
 // We now switch to mobile mode.
 set-window-size: (600, 600)
diff --git a/tests/rustdoc-gui/src/proc_macro_test/Cargo.lock b/tests/rustdoc-gui/src/proc_macro_test/Cargo.lock
new file mode 100644
index 00000000000..eae9d75367f
--- /dev/null
+++ b/tests/rustdoc-gui/src/proc_macro_test/Cargo.lock
@@ -0,0 +1,7 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 3
+
+[[package]]
+name = "proc_macro_test"
+version = "0.1.0"
diff --git a/tests/rustdoc-gui/src/proc_macro_test/Cargo.toml b/tests/rustdoc-gui/src/proc_macro_test/Cargo.toml
new file mode 100644
index 00000000000..768ced65184
--- /dev/null
+++ b/tests/rustdoc-gui/src/proc_macro_test/Cargo.toml
@@ -0,0 +1,8 @@
+[package]
+name = "proc_macro_test"
+version = "0.1.0"
+edition = "2021"
+
+[lib]
+path = "lib.rs"
+proc-macro = true
diff --git a/tests/rustdoc-gui/src/proc_macro_test/lib.rs b/tests/rustdoc-gui/src/proc_macro_test/lib.rs
new file mode 100644
index 00000000000..8a6c62df87c
--- /dev/null
+++ b/tests/rustdoc-gui/src/proc_macro_test/lib.rs
@@ -0,0 +1,11 @@
+use proc_macro::TokenStream;
+
+#[proc_macro]
+pub fn make_answer(_item: TokenStream) -> TokenStream {
+    "fn answer() -> u32 { 42 }".parse().unwrap()
+}
+
+#[proc_macro_derive(HelperAttr, attributes(helper))]
+pub fn derive_helper_attr(_item: TokenStream) -> TokenStream {
+    TokenStream::new()
+}
diff --git a/tests/rustdoc-gui/src/test_docs/lib.rs b/tests/rustdoc-gui/src/test_docs/lib.rs
index c7d115bdb98..0bc777230bf 100644
--- a/tests/rustdoc-gui/src/test_docs/lib.rs
+++ b/tests/rustdoc-gui/src/test_docs/lib.rs
@@ -593,3 +593,21 @@ pub mod foreign_impl_order {
         fn f(&mut self, fg: [u8; 3]) {}
     }
 }
+
+pub mod private {
+    pub struct Tuple(u32, u8);
+    pub struct Struct {
+        a: u8,
+    }
+
+    pub union Union {
+        a: u8,
+        b: u16,
+    }
+
+    pub enum Enum {
+        A,
+        #[doc(hidden)]
+        B,
+    }
+}
diff --git a/tests/rustdoc/where.SWhere_Simd_item-decl.html b/tests/rustdoc/where.SWhere_Simd_item-decl.html
index 46708b9e4e9..1987b1d59f5 100644
--- a/tests/rustdoc/where.SWhere_Simd_item-decl.html
+++ b/tests/rustdoc/where.SWhere_Simd_item-decl.html
@@ -1,3 +1,3 @@
-<pre class="rust item-decl"><code>pub struct Simd&lt;T&gt;(/* private fields */)
+<pre class="rust item-decl"><code>pub struct Simd&lt;T&gt;(<span class="comment">/* private fields */</span>)
 <span class="where">where
-    T: <a class="trait" href="trait.MyTrait.html" title="trait foo::MyTrait">MyTrait</a></span>;</code></pre>
+    T: <a class="trait" href="trait.MyTrait.html" title="trait foo::MyTrait">MyTrait</a></span>;</code></pre>
\ No newline at end of file
diff --git a/tests/rustdoc/where.alpha_trait_decl.html b/tests/rustdoc/where.alpha_trait_decl.html
index 0c0b2d1ceca..2c010ca7c2d 100644
--- a/tests/rustdoc/where.alpha_trait_decl.html
+++ b/tests/rustdoc/where.alpha_trait_decl.html
@@ -1,3 +1,3 @@
-<code>pub struct Alpha&lt;A&gt;(/* private fields */)
+<code>pub struct Alpha&lt;A&gt;(<span class="comment">/* private fields */</span>)
 <span class="where">where
     A: <a class="trait" href="trait.MyTrait.html" title="trait foo::MyTrait">MyTrait</a></span>;</code>
\ No newline at end of file
diff --git a/tests/rustdoc/whitespace-after-where-clause.union.html b/tests/rustdoc/whitespace-after-where-clause.union.html
index 7e0d5f8717a..e63374760d9 100644
--- a/tests/rustdoc/whitespace-after-where-clause.union.html
+++ b/tests/rustdoc/whitespace-after-where-clause.union.html
@@ -1,4 +1,4 @@
 <pre class="rust item-decl"><code>pub union Union&lt;'a, B&gt;<div class="where">where
     B: <a class="trait" href="trait.ToOwned.html" title="trait foo::ToOwned">ToOwned</a>&lt;<a class="primitive" href="{{channel}}/std/primitive.unit.html">()</a>&gt; + ?<a class="trait" href="{{channel}}/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a> + 'a,</div>{
-    /* private fields */
+    <span class="comment">/* private fields */</span>
 }</code></pre>
\ No newline at end of file
diff --git a/tests/rustdoc/whitespace-after-where-clause.union2.html b/tests/rustdoc/whitespace-after-where-clause.union2.html
index 177a161b83a..da984343daa 100644
--- a/tests/rustdoc/whitespace-after-where-clause.union2.html
+++ b/tests/rustdoc/whitespace-after-where-clause.union2.html
@@ -1,3 +1,3 @@
 <pre class="rust item-decl"><code>pub union Union2&lt;'a, B: ?<a class="trait" href="{{channel}}/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a> + <a class="trait" href="trait.ToOwned.html" title="trait foo::ToOwned">ToOwned</a>&lt;<a class="primitive" href="{{channel}}/std/primitive.unit.html">()</a>&gt; + 'a&gt; {
-    /* private fields */
+    <span class="comment">/* private fields */</span>
 }</code></pre>
\ No newline at end of file