user0/rust
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Add new doc(attribute = "...") attribute

Browse source
This commit is contained in:
Guillaume Gomez 2025-06-13 21:01:59 +02:00
parent b41634205b
commit ab0ee84eac
27 changed files with 168 additions and 47 deletions
Download patch file Download diff file Expand all files Collapse all files

38
src/librustdoc/clean/types.rs
View file

@ -226,15 +226,28 @@ impl ExternalCrate {
}
pub(crate) fn keywords(&self, tcx: TyCtxt<'_>) -> impl Iterator<Item = (DefId, Symbol)> {
fn as_keyword(did: DefId, tcx: TyCtxt<'_>) -> Option<(DefId, Symbol)> {
self.retrieve_keywords_or_documented_attributes(tcx, sym::keyword)
}
pub(crate) fn documented_attributes(
&self,
tcx: TyCtxt<'_>,
) -> impl Iterator<Item = (DefId, Symbol)> {
self.retrieve_keywords_or_documented_attributes(tcx, sym::attribute)
}
fn retrieve_keywords_or_documented_attributes(
&self,
tcx: TyCtxt<'_>,
name: Symbol,
) -> impl Iterator<Item = (DefId, Symbol)> {
let as_target = move |did: DefId, tcx: TyCtxt<'_>| -> Option<(DefId, Symbol)> {
tcx.get_attrs(did, sym::doc)
.flat_map(|attr| attr.meta_item_list().unwrap_or_default())
.filter(|meta| meta.has_name(sym::keyword))
.filter(|meta| meta.has_name(name))
.find_map(|meta| meta.value_str())
.map(|value| (did, value))
}
self.mapped_root_modules(tcx, as_keyword)
};
self.mapped_root_modules(tcx, as_target)
}
pub(crate) fn primitives(
@ -592,6 +605,9 @@ impl Item {
pub(crate) fn is_keyword(&self) -> bool {
self.type_() == ItemType::Keyword
}
pub(crate) fn is_attribute(&self) -> bool {
self.type_() == ItemType::Attribute
}
pub(crate) fn is_stripped(&self) -> bool {
match self.kind {
StrippedItem(..) => true,
@ -735,7 +751,9 @@ impl Item {
// Primitives and Keywords are written in the source code as private modules.
// The modules need to be private so that nobody actually uses them, but the
// keywords and primitives that they are documenting are public.
ItemKind::KeywordItem | ItemKind::PrimitiveItem(_) => return Some(Visibility::Public),
ItemKind::KeywordItem | ItemKind::PrimitiveItem(_) | ItemKind::AttributeItem => {
return Some(Visibility::Public);
}
// Variant fields inherit their enum's visibility.
StructFieldItem(..) if is_field_vis_inherited(tcx, def_id) => {
return None;
@ -942,7 +960,12 @@ pub(crate) enum ItemKind {
AssocTypeItem(Box<TypeAlias>, Vec<GenericBound>),
/// An item that has been stripped by a rustdoc pass
StrippedItem(Box<ItemKind>),
/// This item represents a module with a `#[doc(keyword = "...")]` attribute which is used
/// to generate documentation for Rust keywords.
KeywordItem,
/// This item represents a module with a `#[doc(attribute = "...")]` attribute which is used
/// to generate documentation for Rust builtin attributes.
AttributeItem,
}
impl ItemKind {
@ -983,7 +1006,8 @@ impl ItemKind {
| RequiredAssocTypeItem(..)
| AssocTypeItem(..)
| StrippedItem(_)
| KeywordItem => [].iter(),
| KeywordItem
| AttributeItem => [].iter(),
}
}

4
src/librustdoc/clean/utils.rs
View file

@ -60,6 +60,7 @@ pub(crate) fn krate(cx: &mut DocContext<'_>) -> Crate {
let local_crate = ExternalCrate { crate_num: LOCAL_CRATE };
let primitives = local_crate.primitives(cx.tcx);
let keywords = local_crate.keywords(cx.tcx);
let documented_attributes = local_crate.documented_attributes(cx.tcx);
{
let ItemKind::ModuleItem(m) = &mut module.inner.kind else { unreachable!() };
m.items.extend(primitives.map(|(def_id, prim)| {
@ -73,6 +74,9 @@ pub(crate) fn krate(cx: &mut DocContext<'_>) -> Crate {
m.items.extend(keywords.map(|(def_id, kw)| {
Item::from_def_id_and_parts(def_id, Some(kw), ItemKind::KeywordItem, cx)
}));
m.items.extend(documented_attributes.into_iter().map(|(def_id, kw)| {
Item::from_def_id_and_parts(def_id, Some(kw), ItemKind::AttributeItem, cx)
}));
}
Crate { module, external_traits: Box::new(mem::take(&mut cx.external_traits)) }

3
src/librustdoc/fold.rs
View file

@ -96,7 +96,8 @@ pub(crate) trait DocFolder: Sized {
| ImplAssocConstItem(..)
| RequiredAssocTypeItem(..)
| AssocTypeItem(..)
| KeywordItem => kind,
| KeywordItem
| AttributeItem => kind,
}
}

3
src/librustdoc/formats/cache.rs
View file

@ -372,7 +372,8 @@ impl DocFolder for CacheBuilder<'_, '_> {
| clean::RequiredAssocTypeItem(..)
| clean::AssocTypeItem(..)
| clean::StrippedItem(..)
| clean::KeywordItem => {
| clean::KeywordItem
| clean::AttributeItem => {
// FIXME: Do these need handling?
// The person writing this comment doesn't know.
// So would rather leave them to an expert,

3
src/librustdoc/formats/item_type.rs
View file

@ -57,6 +57,7 @@ pub(crate) enum ItemType {
TraitAlias = 25,
// This number is reserved for use in JavaScript
// Generic = 26,
Attribute = 27,
}
impl Serialize for ItemType {
@ -148,6 +149,7 @@ impl<'a> From<&'a clean::Item> for ItemType {
clean::RequiredAssocTypeItem(..) | clean::AssocTypeItem(..) => ItemType::AssocType,
clean::ForeignTypeItem => ItemType::ForeignType,
clean::KeywordItem => ItemType::Keyword,
clean::AttributeItem => ItemType::Attribute,
clean::TraitAliasItem(..) => ItemType::TraitAlias,
clean::ProcMacroItem(mac) => match mac.kind {
MacroKind::Bang => ItemType::Macro,
@ -236,6 +238,7 @@ impl ItemType {
ItemType::ProcAttribute => "attr",
ItemType::ProcDerive => "derive",
ItemType::TraitAlias => "traitalias",
ItemType::Attribute => "attribute",
}
}
pub(crate) fn is_method(&self) -> bool {

2
src/librustdoc/html/render/context.rs
View file

@ -218,7 +218,7 @@ impl<'tcx> Context<'tcx> {
} else {
it.name.as_ref().unwrap().as_str()
};
if !it.is_primitive() && !it.is_keyword() {
if !it.is_primitive() && !it.is_keyword() && !it.is_attribute() {
if !is_module {
title.push_str(" in ");
}

5
src/librustdoc/html/render/mod.rs
View file

@ -2535,6 +2535,7 @@ pub(crate) enum ItemSection {
AssociatedConstants,
ForeignTypes,
Keywords,
Attributes,
AttributeMacros,
DeriveMacros,
TraitAliases,
@ -2567,6 +2568,7 @@ impl ItemSection {
AssociatedConstants,
ForeignTypes,
Keywords,
Attributes,
AttributeMacros,
DeriveMacros,
TraitAliases,
@ -2596,6 +2598,7 @@ impl ItemSection {
Self::AssociatedConstants => "associated-consts",
Self::ForeignTypes => "foreign-types",
Self::Keywords => "keywords",
Self::Attributes => "attributes",
Self::AttributeMacros => "attributes",
Self::DeriveMacros => "derives",
Self::TraitAliases => "trait-aliases",
@ -2625,6 +2628,7 @@ impl ItemSection {
Self::AssociatedConstants => "Associated Constants",
Self::ForeignTypes => "Foreign Types",
Self::Keywords => "Keywords",
Self::Attributes => "Attributes",
Self::AttributeMacros => "Attribute Macros",
Self::DeriveMacros => "Derive Macros",
Self::TraitAliases => "Trait Aliases",
@ -2655,6 +2659,7 @@ fn item_ty_to_section(ty: ItemType) -> ItemSection {
ItemType::AssocConst => ItemSection::AssociatedConstants,
ItemType::ForeignType => ItemSection::ForeignTypes,
ItemType::Keyword => ItemSection::Keywords,
ItemType::Attribute => ItemSection::Attributes,
ItemType::ProcAttribute => ItemSection::AttributeMacros,
ItemType::ProcDerive => ItemSection::DeriveMacros,
ItemType::TraitAlias => ItemSection::TraitAliases,

9
src/librustdoc/html/render/print_item.rs
View file

@ -173,6 +173,7 @@ pub(super) fn print_item(cx: &Context<'_>, item: &clean::Item) -> impl fmt::Disp
clean::ConstantItem(..) => "Constant ",
clean::ForeignTypeItem => "Foreign Type ",
clean::KeywordItem => "Keyword ",
clean::AttributeItem => "Attribute ",
clean::TraitAliasItem(..) => "Trait Alias ",
_ => {
// We don't generate pages for any other type.
@ -193,7 +194,7 @@ pub(super) fn print_item(cx: &Context<'_>, item: &clean::Item) -> impl fmt::Disp
let src_href =
if cx.info.include_sources && !item.is_primitive() { cx.src_href(item) } else { None };
let path_components = if item.is_primitive() || item.is_keyword() {
let path_components = if item.is_primitive() || item.is_keyword() || item.is_attribute() {
vec![]
} else {
let cur = &cx.current;
@ -252,7 +253,9 @@ pub(super) fn print_item(cx: &Context<'_>, item: &clean::Item) -> impl fmt::Disp
clean::ForeignTypeItem => {
write!(buf, "{}", item_foreign_type(cx, item))
}
clean::KeywordItem => write!(buf, "{}", item_keyword(cx, item)),
clean::KeywordItem | clean::AttributeItem => {
write!(buf, "{}", item_keyword_or_attribute(cx, item))
}
clean::TraitAliasItem(ta) => {
write!(buf, "{}", item_trait_alias(cx, item, ta))
}
@ -2151,7 +2154,7 @@ fn item_foreign_type(cx: &Context<'_>, it: &clean::Item) -> impl fmt::Display {
})
}
fn item_keyword(cx: &Context<'_>, it: &clean::Item) -> impl fmt::Display {
fn item_keyword_or_attribute(cx: &Context<'_>, it: &clean::Item) -> impl fmt::Display {
document(cx, it, None, HeadingOffset::H2)
}

2
src/librustdoc/html/static/css/noscript.css
View file

@ -75,6 +75,7 @@ nav.sub {
--function-link-color: #ad7c37;
--macro-link-color: #068000;
--keyword-link-color: #3873ad;
--attribute-link-color: #3873ad;
--mod-link-color: #3873ad;
--link-color: #3873ad;
--sidebar-link-color: #356da4;
@ -180,6 +181,7 @@ nav.sub {
--function-link-color: #2bab63;
--macro-link-color: #09bd00;
--keyword-link-color: #d2991d;
--attribute-link-color: #d2991d;
--mod-link-color: #d2991d;
--link-color: #d2991d;
--sidebar-link-color: #fdbf35;

7
src/librustdoc/html/static/css/rustdoc.css
View file

@ -400,6 +400,10 @@ span.keyword, a.keyword {
color: var(--keyword-link-color);
}
span.attribute, a.attribute {
color: var(--attribute-link-color);
}
a {
color: var(--link-color);
text-decoration: none;
@ -3190,6 +3194,7 @@ by default.
--function-link-color: #ad7c37;
--macro-link-color: #068000;
--keyword-link-color: #3873ad;
--attribute-link-color: #3873ad;
--mod-link-color: #3873ad;
--link-color: #3873ad;
--sidebar-link-color: #356da4;
@ -3294,6 +3299,7 @@ by default.
--function-link-color: #2bab63;
--macro-link-color: #09bd00;
--keyword-link-color: #d2991d;
--attribute-link-color: #d2991d;
--mod-link-color: #d2991d;
--link-color: #d2991d;
--sidebar-link-color: #fdbf35;
@ -3407,6 +3413,7 @@ Original by Dempfi (https://github.com/dempfi/ayu)
--function-link-color: #fdd687;
--macro-link-color: #a37acc;
--keyword-link-color: #39afd7;
--attribute-link-color: #39afd7;
--mod-link-color: #39afd7;
--link-color: #39afd7;
--sidebar-link-color: #53b1db;

1
src/librustdoc/html/static/js/main.js
View file

@ -790,6 +790,7 @@ function preLoadCss(cssUrl) {
//block("associatedconstant", "associated-consts", "Associated Constants");
block("foreigntype", "foreign-types", "Foreign Types");
block("keyword", "keywords", "Keywords");
block("attribute", "attributes", "Attributes");
block("attr", "attributes", "Attribute Macros");
block("derive", "derives", "Derive Macros");
block("traitalias", "trait-aliases", "Trait Aliases");

5
src/librustdoc/html/static/js/search.js
View file

@ -119,6 +119,7 @@ const itemTypes = [
"derive",
"traitalias", // 25
"generic",
"attribute",
];
// used for special search precedence
@ -2058,7 +2059,7 @@ class DocSearch {
displayPath = item.modulePath + "::";
href = this.rootPath + item.modulePath.replace(/::/g, "/") +
"/index.html#reexport." + name;
} else if (type === "primitive" || type === "keyword") {
} else if (type === "primitive" || type === "keyword" || type === "attribute") {
displayPath = "";
exactPath = "";
href = this.rootPath + path.replace(/::/g, "/") +
@ -4560,6 +4561,8 @@ const longItemTypes = [
"attribute macro",
"derive macro",
"trait alias",
"",
"attribute",
];
// @ts-expect-error
let currentResults;

14
src/librustdoc/json/conversions.rs
View file

@ -52,7 +52,7 @@ impl JsonRenderer<'_> {
let clean::ItemInner { name, item_id, .. } = *item.inner;
let id = self.id_from_item(item);
let inner = match item.kind {
clean::KeywordItem => return None,
clean::KeywordItem | clean::AttributeItem => return None,
clean::StrippedItem(ref inner) => {
match &**inner {
// We document stripped modules as with `Module::is_stripped` set to
@ -85,7 +85,7 @@ impl JsonRenderer<'_> {
fn ids(&self, items: &[clean::Item]) -> Vec<Id> {
items
.iter()
.filter(|i| !i.is_stripped() && !i.is_keyword())
.filter(|i| !i.is_stripped() && !i.is_keyword() && !i.is_attribute())
.map(|i| self.id_from_item(i))
.collect()
}
@ -93,7 +93,10 @@ impl JsonRenderer<'_> {
fn ids_keeping_stripped(&self, items: &[clean::Item]) -> Vec<Option<Id>> {
items
.iter()
.map(|i| (!i.is_stripped() && !i.is_keyword()).then(|| self.id_from_item(i)))
.map(|i| {
(!i.is_stripped() && !i.is_keyword() && !i.is_attribute())
.then(|| self.id_from_item(i))
})
.collect()
}
}
@ -332,8 +335,8 @@ fn from_clean_item(item: &clean::Item, renderer: &JsonRenderer<'_>) -> ItemEnum
bounds: b.into_json(renderer),
type_: Some(t.item_type.as_ref().unwrap_or(&t.type_).into_json(renderer)),
},
// `convert_item` early returns `None` for stripped items and keywords.
KeywordItem => unreachable!(),
// `convert_item` early returns `None` for stripped items, keywords and attributes.
KeywordItem | AttributeItem => unreachable!(),
StrippedItem(inner) => {
match inner.as_ref() {
ModuleItem(m) => ItemEnum::Module(Module {
@ -887,6 +890,7 @@ impl FromClean<ItemType> for ItemKind {
AssocType => ItemKind::AssocType,
ForeignType => ItemKind::ExternType,
Keyword => ItemKind::Keyword,
Attribute => ItemKind::Attribute,
TraitAlias => ItemKind::TraitAlias,
ProcAttribute => ItemKind::ProcAttribute,
ProcDerive => ItemKind::ProcDerive,

1
src/librustdoc/passes/check_doc_test_visibility.rs
View file

@ -67,6 +67,7 @@ pub(crate) fn should_have_doc_example(cx: &DocContext<'_>, item: &clean::Item) -
| clean::ImportItem(_)
| clean::PrimitiveItem(_)
| clean::KeywordItem
| clean::AttributeItem
| clean::ModuleItem(_)
| clean::TraitAliasItem(_)
| clean::ForeignFunctionItem(..)

4
src/librustdoc/passes/collect_intra_doc_links.rs
View file

@ -19,7 +19,7 @@ use rustc_hir::{Mutability, Safety};
use rustc_middle::ty::{Ty, TyCtxt};
use rustc_middle::{bug, span_bug, ty};
use rustc_resolve::rustdoc::{
MalformedGenerics, has_primitive_or_keyword_docs, prepare_to_doc_link_resolution,
MalformedGenerics, has_primitive_or_keyword_or_attribute_docs, prepare_to_doc_link_resolution,
source_span_for_markdown_range, strip_generics_from_path,
};
use rustc_session::config::CrateType;
@ -1073,7 +1073,7 @@ impl LinkCollector<'_, '_> {
&& let Some(def_id) = item.item_id.as_def_id()
&& let Some(def_id) = def_id.as_local()
&& !self.cx.tcx.effective_visibilities(()).is_exported(def_id)
&& !has_primitive_or_keyword_docs(&item.attrs.other_attrs)
&& !has_primitive_or_keyword_or_attribute_docs(&item.attrs.other_attrs)
{
// Skip link resolution for non-exported items.
return;

3
src/librustdoc/passes/propagate_stability.rs
View file

@ -106,7 +106,8 @@ impl DocFolder for StabilityPropagator<'_, '_> {
| ItemKind::RequiredAssocTypeItem(..)
| ItemKind::AssocTypeItem(..)
| ItemKind::PrimitiveItem(..)
| ItemKind::KeywordItem => own_stability,
| ItemKind::KeywordItem
| ItemKind::AttributeItem => own_stability,
ItemKind::StrippedItem(..) => unreachable!(),
}

2
src/librustdoc/passes/stripper.rs
View file

@ -133,6 +133,8 @@ impl DocFolder for Stripper<'_, '_> {
// Keywords are never stripped
clean::KeywordItem => {}
// Attributes are never stripped
clean::AttributeItem => {}
}
let fastreturn = match i.kind {

3
src/librustdoc/visit.rs
View file

@ -49,7 +49,8 @@ pub(crate) trait DocVisitor<'a>: Sized {
| ImplAssocConstItem(..)
| RequiredAssocTypeItem(..)
| AssocTypeItem(..)
| KeywordItem => {}
| KeywordItem
| AttributeItem => {}
}
}

9
src/rustdoc-json-types/lib.rs
View file

@ -37,8 +37,8 @@ pub type FxHashMap<K, V> = HashMap<K, V>; // re-export for use in src/librustdoc
// will instead cause conflicts. See #94591 for more. (This paragraph and the "Latest feature" line
// are deliberately not in a doc comment, because they need not be in public docs.)
//
// Latest feature: Add Attribute::MacroUse
pub const FORMAT_VERSION: u32 = 55;
// Latest feature: Add `ItemKind::Attribute`.
pub const FORMAT_VERSION: u32 = 56;
/// The root of the emitted JSON blob.
///
@ -552,6 +552,11 @@ pub enum ItemKind {
/// [`Item`]s of this kind only come from the come library and exist solely
/// to carry documentation for the respective keywords.
Keyword,
/// An attribute declaration.
///
/// [`Item`]s of this kind only come from the core library and exist solely
/// to carry documentation for the respective builtin attributes.
Attribute,
}
/// Specific fields of an item.

4
src/tools/jsondoclint/src/item_kind.rs
View file

@ -26,6 +26,7 @@ pub(crate) enum Kind {
AssocType,
Primitive,
Keyword,
Attribute,
// Not in ItemKind
ProcMacro,
}
@ -53,6 +54,7 @@ impl Kind {
ExternType => true,
// FIXME(adotinthevoid): I'm not sure if these are correct
Attribute => false,
Keyword => false,
ProcAttribute => false,
ProcDerive => false,
@ -109,6 +111,7 @@ impl Kind {
Kind::Primitive => false,
Kind::Keyword => false,
Kind::ProcMacro => false,
Kind::Attribute => false,
}
}
@ -163,6 +166,7 @@ impl Kind {
match s.kind {
ItemKind::AssocConst => AssocConst,
ItemKind::AssocType => AssocType,
ItemKind::Attribute => Attribute,
ItemKind::Constant => Constant,
ItemKind::Enum => Enum,
ItemKind::ExternCrate => ExternCrate,