rustdoc: notable trait badge color attribute

compiler/rustc_attr_parsing/src/attributes/doc.rs

@@ -5,7 +5,7 @@ use rustc_feature::AttributeStability;
 use rustc_hir::Target;
 use rustc_hir::attrs::{
     AttributeKind, CfgEntry, CfgHideShow, DocAttribute, DocCfgHideShow, DocCfgHideShowValue,
-    DocInline, HideOrShow,
+    DocInline, HideOrShow, NotableTraitColor,
 };
 use rustc_session::diagnostics::feature_err;
 use rustc_span::{Span, Symbol, edition, sym};
@@ -19,14 +19,15 @@ use crate::diagnostics::{
     DocAutoCfgHideShowUnexpectedItem, DocAutoCfgHideShowUnexpectedItemAfterValues,
     DocAutoCfgHideShowValuesMix, DocAutoCfgWrongLiteral, DocTestLiteral, DocTestTakesList,
     DocTestUnknown, DocUnknownAny, DocUnknownInclude, DocUnknownPasses, DocUnknownPlugins,
-    DocUnknownSpotlight, ExpectedNameValue, ExpectedNoArgs, IllFormedAttributeInput, MalformedDoc,
+    DocUnknownSpotlight, ExpectedNameValue, ExpectedNoArgs, IllFormedAttributeInput,
+    InvalidNotableTraitAttr, MalformedDoc,
 };
 use crate::parser::{
     ArgParser, MetaItemListParser, MetaItemOrLitParser, MetaItemParser, OwnedPathParser,
 };
 use crate::session_diagnostics::{
     DocAliasBadChar, DocAliasEmpty, DocAliasMalformed, DocAliasStartEnd, DocAttrNotCrateLevel,
-    DocAttributeNotAttribute, DocKeywordNotKeyword, UnusedDuplicate,
+    DocAttrTraitLevel, DocAttributeNotAttribute, DocKeywordNotKeyword, UnusedDuplicate,
 };
 
 fn check_keyword(cx: &mut AcceptContext<'_, '_>, keyword: Symbol, span: Span) -> bool {
@@ -98,6 +99,110 @@ fn expected_string_literal(
     cx.emit_lint(rustc_session::lint::builtin::INVALID_DOC_ATTRIBUTES, MalformedDoc, span);
 }
 
+fn parse_notable_trait(
+    cx: &mut AcceptContext<'_, '_>,
+    path: &OwnedPathParser,
+    args: &ArgParser,
+    attr_value: &mut Option<(Option<(NotableTraitColor, Span)>, Span)>,
+    attr_name: Symbol,
+) {
+    let span = path.span();
+
+    let notable_trait_color_attr = match args {
+        ArgParser::NoArgs => None,
+        ArgParser::List(meta_item_list_parser) => {
+            if meta_item_list_parser.is_empty() {
+                None
+            } else if let Some(meta_item) = meta_item_list_parser.as_single() {
+                Some(meta_item)
+            } else {
+                cx.emit_lint(
+                    rustc_session::lint::builtin::INVALID_DOC_ATTRIBUTES,
+                    InvalidNotableTraitAttr,
+                    span,
+                );
+                return;
+            }
+        }
+        ArgParser::NameValue(_) => {
+            cx.emit_lint(
+                rustc_session::lint::builtin::INVALID_DOC_ATTRIBUTES,
+                InvalidNotableTraitAttr,
+                span,
+            );
+            return;
+        }
+    };
+
+    let notable_trait_color_and_span =
+        if let Some(notable_trait_color_attr) = notable_trait_color_attr {
+            let Some(notable_trait_color_attr) = notable_trait_color_attr.meta_item() else {
+                cx.emit_lint(
+                    rustc_session::lint::builtin::INVALID_DOC_ATTRIBUTES,
+                    InvalidNotableTraitAttr,
+                    span,
+                );
+                return;
+            };
+            if !notable_trait_color_attr.path().word_is(sym::color) {
+                cx.emit_lint(
+                    rustc_session::lint::builtin::INVALID_DOC_ATTRIBUTES,
+                    InvalidNotableTraitAttr,
+                    span,
+                );
+                return;
+            }
+            let Some(notable_trait_color) = notable_trait_color_attr.args().as_name_value() else {
+                cx.emit_lint(
+                    rustc_session::lint::builtin::INVALID_DOC_ATTRIBUTES,
+                    InvalidNotableTraitAttr,
+                    span,
+                );
+                return;
+            };
+            let Some(notable_trait_color) = notable_trait_color.value_as_str() else {
+                cx.emit_lint(
+                    rustc_session::lint::builtin::INVALID_DOC_ATTRIBUTES,
+                    InvalidNotableTraitAttr,
+                    span,
+                );
+                return;
+            };
+            let notable_trait_color = match notable_trait_color.as_str() {
+                "grey" => NotableTraitColor::Grey,
+                "red" => NotableTraitColor::Red,
+                "green" => NotableTraitColor::Green,
+                "yellow" => NotableTraitColor::Yellow,
+                "blue" => NotableTraitColor::Blue,
+                "magenta" => NotableTraitColor::Magenta,
+                "cyan" => NotableTraitColor::Cyan,
+                "transparent" => NotableTraitColor::Transparent,
+                _ => {
+                    cx.emit_lint(
+                        rustc_session::lint::builtin::INVALID_DOC_ATTRIBUTES,
+                        InvalidNotableTraitAttr,
+                        span,
+                    );
+                    return;
+                }
+            };
+            Some((notable_trait_color, notable_trait_color_attr.span()))
+        } else {
+            None
+        };
+
+    if cx.shared.target != Target::Trait {
+        cx.emit_lint(
+            rustc_session::lint::builtin::INVALID_DOC_ATTRIBUTES,
+            DocAttrTraitLevel { span, attr_name },
+            span,
+        );
+        return;
+    }
+
+    *attr_value = Some((notable_trait_color_and_span, span));
+}
+
 fn parse_keyword_and_attribute(
     cx: &mut AcceptContext<'_, '_>,
     path: &OwnedPathParser,
@@ -610,7 +715,13 @@ impl DocParser {
             Some(sym::no_inline) => self.parse_inline(cx, path, args, DocInline::NoInline),
             Some(sym::masked) => no_args!(masked),
             Some(sym::cfg) => self.parse_cfg(cx, args),
-            Some(sym::notable_trait) => no_args!(notable_trait),
+            Some(sym::notable_trait) => parse_notable_trait(
+                cx,
+                path,
+                args,
+                &mut self.attribute.notable_trait,
+                sym::notable_trait,
+            ),
             Some(sym::keyword) => parse_keyword_and_attribute(
                 cx,
                 path,

compiler/rustc_attr_parsing/src/diagnostics.rs

@@ -319,6 +319,13 @@ pub(crate) struct ExpectedNoArgs;
 )]
 pub(crate) struct ExpectedNameValue;
 
+#[derive(Diagnostic)]
+#[diag("expected either `doc(notable_trait)` or `doc(notable_trait=\"...\")`")]
+#[warning(
+    "this was previously accepted by the compiler but is being phased out; it will become a hard error in a future release!"
+)]
+pub(crate) struct InvalidNotableTraitAttr;
+
 #[derive(Diagnostic)]
 #[diag("malformed `{$attribute}` attribute")]
 #[help("{$options}")]

compiler/rustc_attr_parsing/src/session_diagnostics.rs

@@ -89,6 +89,17 @@ pub(crate) struct DocAttrNotCrateLevel {
     pub attr_name: Symbol,
 }
 
+#[derive(Diagnostic)]
+#[diag("`#![doc({$attr_name})]` must be a trait attribute")]
+#[warning(
+    "this was previously accepted by the compiler but is being phased out; it will become a hard error in a future release!"
+)]
+pub(crate) struct DocAttrTraitLevel {
+    #[primary_span]
+    pub span: Span,
+    pub attr_name: Symbol,
+}
+
 #[derive(Diagnostic)]
 #[diag("nonexistent keyword `{$keyword}` used in `#[doc(keyword = \"...\")]`")]
 #[help("only existing keywords are allowed in core/std")]

compiler/rustc_hir/src/attrs/data_structures.rs

@@ -596,7 +596,7 @@ pub struct DocAttribute {
     pub keyword: Option<(Symbol, Span)>,
     pub attribute: Option<(Symbol, Span)>,
     pub masked: Option<Span>,
-    pub notable_trait: Option<Span>,
+    pub notable_trait: Option<(Option<(NotableTraitColor, Span)>, Span)>,
     pub search_unbox: Option<Span>,
 
     // valid on crate
@@ -613,6 +613,41 @@ pub struct DocAttribute {
     pub no_crate_inject: Option<Span>,
 }
 
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+#[derive(StableHash, Encodable, Decodable, PrintAttribute)]
+pub enum NotableTraitColor {
+    Grey,
+    Red,
+    Green,
+    Yellow,
+    Blue,
+    Magenta,
+    Cyan,
+    Transparent,
+}
+
+impl Into<&'static str> for NotableTraitColor {
+    fn into(self) -> &'static str {
+        use NotableTraitColor::*;
+        match self {
+            Grey => "grey",
+            Red => "red",
+            Green => "green",
+            Yellow => "yellow",
+            Blue => "blue",
+            Magenta => "magenta",
+            Cyan => "cyan",
+            Transparent => "transparent",
+        }
+    }
+}
+
+impl std::fmt::Display for NotableTraitColor {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        std::fmt::Display::fmt(<NotableTraitColor as Into<&str>>::into(*self), f)
+    }
+}
+
 impl<E: rustc_span::SpanEncoder> rustc_serialize::Encodable<E> for DocAttribute {
     fn encode(&self, encoder: &mut E) {
         let DocAttribute {

compiler/rustc_middle/src/queries.rs

@@ -60,7 +60,7 @@ use rustc_data_structures::svh::Svh;
 use rustc_data_structures::unord::{UnordMap, UnordSet};
 use rustc_errors::{ErrorGuaranteed, catch_fatal_errors};
 use rustc_hir as hir;
-use rustc_hir::attrs::{CanonicalSymbols, EiiDecl, EiiImpl, StrippedCfgItem};
+use rustc_hir::attrs::{CanonicalSymbols, EiiDecl, EiiImpl, NotableTraitColor, StrippedCfgItem};
 use rustc_hir::def::{DefKind, DocLinkResMap};
 use rustc_hir::def_id::{CrateNum, DefId, DefIdMap, LocalDefId, LocalDefIdSet, LocalModId};
 use rustc_hir::lang_items::{LangItem, LanguageItems};
@@ -1504,8 +1504,10 @@ rustc_queries! {
         separate_provide_extern
     }
 
-    /// Determines whether an item is annotated with `#[doc(notable_trait)]`.
-    query is_doc_notable_trait(def_id: DefId) -> bool {
+    /// If an item is annotated with `#[doc(notable_trait)]`,
+    /// returns the color used to render its pill. If the crate specifies
+    /// no color, `Transparent` is used.
+    query doc_notable_trait(def_id: DefId) -> Option<&'tcx NotableTraitColor> {
         desc { "checking whether `{}` is `doc(notable_trait)`", tcx.def_path_str(def_id) }
     }
 

compiler/rustc_middle/src/ty/util.rs

@@ -10,6 +10,7 @@ use rustc_data_structures::stable_hash::{StableHash, StableHasher};
 use rustc_data_structures::stack::ensure_sufficient_stack;
 use rustc_errors::ErrorGuaranteed;
 use rustc_hashes::Hash128;
+use rustc_hir::attrs::NotableTraitColor;
 use rustc_hir::def::{CtorOf, DefKind, Res};
 use rustc_hir::def_id::{CrateNum, DefId, LocalDefId};
 use rustc_hir::{self as hir, find_attr};
@@ -1700,8 +1701,15 @@ fn is_doc_hidden(tcx: TyCtxt<'_>, def_id: LocalDefId) -> bool {
 }
 
 /// Determines whether an item is annotated with `doc(notable_trait)`.
-pub fn is_doc_notable_trait(tcx: TyCtxt<'_>, def_id: DefId) -> bool {
-    find_attr!(tcx, def_id, Doc(doc) if doc.notable_trait.is_some())
+pub fn doc_notable_trait(tcx: TyCtxt<'_>, def_id: DefId) -> Option<&'_ NotableTraitColor> {
+    find_attr!(tcx, def_id, Doc(doc) if doc.notable_trait.is_some() => {
+        let (color, _span) = doc.notable_trait.as_ref()?;
+        if let Some((color, _span)) = color {
+            color
+        } else {
+            &NotableTraitColor::Transparent
+        }
+    })
 }
 
 /// Determines whether an item is an intrinsic (which may be via Abi or via the `rustc_intrinsic` attribute).
@@ -1731,7 +1739,7 @@ pub fn provide(providers: &mut Providers) {
     *providers = Providers {
         reveal_opaque_types_in_bounds,
         is_doc_hidden,
-        is_doc_notable_trait,
+        doc_notable_trait,
         intrinsic_raw,
         ..*providers
     }

compiler/rustc_span/src/symbol.rs

@@ -641,6 +641,7 @@ symbols! {
         cold,
         cold_path,
         collapse_debuginfo,
+        color,
         column,
         common,
         compare_bytes,

library/alloc/src/io/read.rs

@@ -82,7 +82,7 @@ use crate::vec::Vec;
 /// [`&str`]: prim@str
 /// [`std::io`]: crate::io
 #[stable(feature = "rust1", since = "1.0.0")]
-#[doc(notable_trait)]
+#[doc(notable_trait(color = "grey"))]
 #[cfg_attr(not(test), rustc_diagnostic_item = "IoRead")]
 pub trait Read {
     /// Pull some bytes from this source into the specified buffer, returning

library/core/src/future/future.rs

@@ -25,7 +25,7 @@ use crate::task::{Context, Poll};
 ///
 /// [`async`]: ../../std/keyword.async.html
 /// [`Waker`]: crate::task::Waker
-#[doc(notable_trait)]
+#[doc(notable_trait(color = "blue"))]
 #[doc(search_unbox)]
 #[must_use = "futures do nothing unless you `.await` or poll them"]
 #[stable(feature = "futures_api", since = "1.36.0")]

library/core/src/io/write.rs

@@ -47,7 +47,7 @@ use crate::io::{Error, IoSlice, Result};
 ///
 /// [`write_all`]: Write::write_all
 #[stable(feature = "rust1", since = "1.0.0")]
-#[doc(notable_trait)]
+#[doc(notable_trait(color = "grey"))]
 #[cfg_attr(not(test), rustc_diagnostic_item = "IoWrite")]
 pub trait Write {
     /// Writes a buffer into this writer, returning how many bytes were written.

library/core/src/iter/traits/iterator.rs

@@ -34,7 +34,7 @@ fn _assert_is_dyn_compatible(_: &dyn Iterator<Item = ()>) {}
     label = "`{Self}` is not an iterator",
     message = "`{Self}` is not an iterator"
 )]
-#[doc(notable_trait)]
+#[doc(notable_trait(color = "blue"))]
 #[lang = "iterator"]
 #[rustc_diagnostic_item = "Iterator"]
 #[must_use = "iterators are lazy and do nothing unless consumed"]