Rename `#[doc(spotlight)]` to `#[doc(notable_trait)]` #80965

camelid · 2021-01-13T04:19:53Z

"spotlight" is not a very specific or self-explaining name.
Additionally, the dialog that it triggers is called "Notable traits".
So, "notable trait" is a better name.

Rename #[doc(spotlight)] to #[doc(notable_trait)]
Rename #![feature(doc_spotlight)] to #![feature(doc_notable_trait)]
Update documentation
Improve documentation

r? @Manishearth

camelid · 2021-01-13T04:20:26Z

Dang, I wish git add src/ wouldn't add submodules.

Manishearth · 2021-01-13T04:23:20Z

r=me once @jyn514 and @GuillaumeGomez have a chance to approve the new name

camelid · 2021-01-13T04:25:14Z

Note that #[doc(spotlight)] will fail as if it never existed. However, it's probably fine because:

it's a niche feature, and
#![feature(doc_spotlight)] should point towards the new feature flag

camelid · 2021-01-13T04:31:29Z

Also note that this only changes the user interface; internally in rustdoc it's still called spotlight. That's because this will likely conflict with #80914 and I want to minimize the conflicts and unnecessary work :)

camelid · 2021-01-13T04:33:32Z

I used my own rustc-dev-guide docs for this ^^

jyn514 · 2021-01-13T04:42:55Z

I would strongly prefer to deprecate spotlight and have it to suggest using notable_trait instead. Otherwise people won't know where it went and be very confused.

jyn514 · 2021-01-13T04:44:50Z

Oh, you did that, sorry. I didn't realize it from the PR description.

jyn514 · 2021-01-13T04:45:15Z

Can you add a test that doc(spotlight) suggests using notable_trait instead?

camelid · 2021-01-13T04:46:24Z

Oh, you did that, sorry. I didn't realize it from the PR description.

I used the established method for renaming the feature gate, but #[doc(spotlight)] will silently do nothing. However, any real code will be using the feature flag so it's probably not a big deal. If you have a better idea, I'm happy to try it!

src/librustdoc/clean/inline.rs

camelid · 2021-01-13T05:50:39Z

Huh, why did this test fail?

---- [ui] ui/panic-handler/weak-lang-item.rs stdout ----
diff of stderr:

10	LL | extern crate core as other_core;
11	   |
12	
-	error: language item required, but not found: `eh_personality`
-	
15	error: `#[panic_handler]` function required, but not found
+	
+	error: language item required, but not found: `eh_personality`
16	
17	error: aborting due to 3 previous errors
18

Seems like a weird spurious issue...

"spotlight" is not a very specific or self-explaining name. Additionally, the dialog that it triggers is called "Notable traits". So, "notable trait" is a better name. * Rename `#[doc(spotlight)]` to `#[doc(notable_trait)]` * Rename `#![feature(doc_spotlight)]` to `#![feature(doc_notable_trait)]` * Update documentation * Improve documentation

bstrie · 2021-03-31T21:03:54Z

Triage: can any of the reviewers here weigh in on the new revision?

jyn514

Sorry for the delay. r=me with the nit addressed.

jyn514 · 2021-03-31T21:28:28Z

compiler/rustc_passes/src/check_attr.rs

+                                            String::from("notable_trait"),
+                                            Applicability::MachineApplicable,
+                                        );
+                                        diag.note("`doc(spotlight)` is now a no-op");


Nah, this seems fine.

jyn514 · 2021-03-31T21:29:26Z

src/doc/rustdoc/src/unstable-features.md

+Rustdoc keeps a list of a few traits that are believed to be "fundamental" to
+types that implement them. These traits are intended to be the primary interface
+for their implementers, and are often most of the API available to be documented
+on their types. For this reason, Rustdoc will track when a given type implements
+one of these traits and call special attention to it when a function returns one
+of these types. This is the "Notable traits" dialog, accessible as a circled `i`
+button next to the function, which, when clicked, shows the dialog.
+
+In the standard library, some of the traits that are part of this list are
+`Iterator`, `Future`, `io::Read`, and `io::Write`. However, rather than being
+implemented as a hard-coded list, these traits have a special marker attribute
+on them: `#[doc(notable_trait)]`. This means that you can apply this attribute
+to your own trait to include it in the "Notable traits" dialog in documentation.
+
+The `#[doc(notable_trait)]` attribute currently requires the `#![feature(doc_notable_trait)]`
+feature gate. For more information, see [its chapter in the Unstable Book][unstable-notable_trait]
+and [its tracking issue][issue-notable_trait].
+
+[unstable-notable_trait]: ../unstable-book/language-features/doc-notable-trait.html
+[issue-notable_trait]: https://github.com/rust-lang/rust/issues/45040


nit: is there a reason you rewrapped this? Did you change any of the text or just the wrapping?

I did change the text; I changed mentions of "spotlight" to "notable trait", and I tweaked some of the wording. Sorry for the re-wrap, I know it's hard to review. I use gqap in Vim whenever I add text so that I don't end up with super long lines.

Here's the Git word-diff output, which should hopefully be easier to review:

diff --git a/old.md b/new.md index 02a6f7b..92322be 100644 --- a/old.md +++ b/new.md @@ -1,20 +1,22 @@ ### Adding your trait to the [-"Important Traits"-]{+"Notable traits"+} dialog Rustdoc keeps a list of a few traits that are believed to be "fundamental" to [-a given type when-] [-implemented on it.-]{+types that implement them.+} These traits are intended to be the primary interface for their [-types,-]{+implementers,+} and are often {+most of+} the [-only thing-]{+API+} available to be documented on their types. For this reason, Rustdoc will track when a given type implements one of these traits and call special attention to it when a function returns one of these types. This is the [-"Important Traits"-]{+"Notable traits"+} dialog, [-visible-]{+accessible+} as a [-circle-i-]{+circled `i`+} button next to the function, which, when clicked, shows the dialog. In the standard library, {+some of+} the traits that [-qualify for inclusion-]{+are part of this list+} are `Iterator`, {+`Future`,+} `io::Read`, and `io::Write`. However, rather than being implemented as a hard-coded list, these traits have a special marker attribute on them: [-`#[doc(spotlight)]`.-]{+`#[doc(notable_trait)]`.+} This means that you [-could-]{+can+} apply this attribute to your own trait to include it in the [-"Important Traits"-]{+"Notable traits"+} dialog in documentation. The [-`#[doc(spotlight)]`-]{+`#[doc(notable_trait)]`+} attribute currently requires the [-`#![feature(doc_spotlight)]`-]{+`#![feature(doc_notable_trait)]`+} feature gate. For more information, see [its chapter in the Unstable [-Book][unstable-spotlight]-]{+Book][unstable-notable_trait]+} and [its tracking [-issue][issue-spotlight].-]{+issue][issue-notable_trait].+} [-[unstable-spotlight]: ../unstable-book/language-features/doc-spotlight.html-] [-[issue-spotlight]:-]{+[unstable-notable_trait]: ../unstable-book/language-features/doc-notable-trait.html+} {+[issue-notable_trait]:+} https://github.com/rust-lang/rust/issues/45040

Ok cool, I am not sure all those changes are improvements but they at least don't seem strictly worse.

jyn514 · 2021-04-01T19:08:47Z

@bors r+

bors · 2021-04-01T19:08:48Z

📌 Commit 34c6cee has been approved by jyn514

Rename `#[doc(spotlight)]` to `#[doc(notable_trait)]` Fixes rust-lang#80936. "spotlight" is not a very specific or self-explaining name. Additionally, the dialog that it triggers is called "Notable traits". So, "notable trait" is a better name. * Rename `#[doc(spotlight)]` to `#[doc(notable_trait)]` * Rename `#![feature(doc_spotlight)]` to `#![feature(doc_notable_trait)]` * Update documentation * Improve documentation r? `@Manishearth`

bors · 2021-04-02T07:05:03Z

⌛ Testing commit 34c6cee with merge 5662d93...

bors · 2021-04-02T09:26:12Z

☀️ Test successful - checks-actions
Approved by: jyn514
Pushing 5662d93 to master...

I didn't make these renames in rust-lang#80965 because I didn't want the PR to conflict with rust-lang#80914.

…ht, r=GuillaumeGomez rustdoc: Rename internal uses of `spotlight` I didn't make these renames in rust-lang#80965 because I didn't want the PR to conflict with rust-lang#80914.

camelid added A-trait-system Area: Trait system C-enhancement Category: An issue proposing an enhancement or a PR with one. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. labels Jan 13, 2021

rust-highfive assigned Manishearth Jan 13, 2021