Support new bang macro kinds in rustdoc

Author: GuillaumeGomez

src/librustdoc/clean/inline.rs

@@ -140,13 +140,12 @@ pub(crate) fn try_inline(
         Res::Def(DefKind::Macro(kinds), did) => {
             let mac = build_macro(cx, did, name, kinds);
 
-            // FIXME: handle attributes and derives that aren't proc macros, and macros with
-            // multiple kinds
             let type_kind = match kinds {
                 MacroKinds::BANG => ItemType::Macro,
                 MacroKinds::ATTR => ItemType::ProcAttribute,
                 MacroKinds::DERIVE => ItemType::ProcDerive,
-                _ => todo!("Handle macros with multiple kinds"),
+                _ if kinds.contains(MacroKinds::BANG) => ItemType::Macro,
+                _ => panic!("unsupported macro kind {kinds:?}"),
             };
             record_extern_fqn(cx, did, type_kind);
             mac
@@ -764,13 +763,14 @@ fn build_macro(
     macro_kinds: MacroKinds,
 ) -> clean::ItemKind {
     match CStore::from_tcx(cx.tcx).load_macro_untracked(def_id, cx.tcx) {
-        // FIXME: handle attributes and derives that aren't proc macros, and macros with multiple
-        // kinds
         LoadedMacro::MacroDef { def, .. } => match macro_kinds {
-            MacroKinds::BANG => clean::MacroItem(clean::Macro {
-                source: utils::display_macro_source(cx, name, &def),
-                macro_rules: def.macro_rules,
-            }),
+            MacroKinds::BANG => clean::MacroItem(
+                clean::Macro {
+                    source: utils::display_macro_source(cx, name, &def),
+                    macro_rules: def.macro_rules,
+                },
+                None,
+            ),
             MacroKinds::DERIVE => clean::ProcMacroItem(clean::ProcMacro {
                 kind: MacroKind::Derive,
                 helpers: Vec::new(),
@@ -779,7 +779,14 @@ fn build_macro(
                 kind: MacroKind::Attr,
                 helpers: Vec::new(),
             }),
-            _ => todo!("Handle macros with multiple kinds"),
+            _ if macro_kinds == (MacroKinds::BANG | MacroKinds::ATTR) => clean::MacroItem(
+                clean::Macro {
+                    source: utils::display_macro_source(cx, name, &def),
+                    macro_rules: def.macro_rules,
+                },
+                Some(macro_kinds),
+            ),
+            _ => panic!("unsupported macro kind {macro_kinds:?}"),
         },
         LoadedMacro::ProcMacro(ext) => {
             // Proc macros can only have a single kind

src/librustdoc/clean/mod.rs

@@ -2841,19 +2841,24 @@ fn clean_maybe_renamed_item<'tcx>(
                 generics: clean_generics(generics, cx),
                 fields: variant_data.fields().iter().map(|x| clean_field(x, cx)).collect(),
             }),
-            // FIXME: handle attributes and derives that aren't proc macros, and macros with
-            // multiple kinds
-            ItemKind::Macro(_, macro_def, MacroKinds::BANG) => MacroItem(Macro {
-                source: display_macro_source(cx, name, macro_def),
-                macro_rules: macro_def.macro_rules,
-            }),
-            ItemKind::Macro(_, _, MacroKinds::ATTR) => {
-                clean_proc_macro(item, &mut name, MacroKind::Attr, cx)
-            }
-            ItemKind::Macro(_, _, MacroKinds::DERIVE) => {
-                clean_proc_macro(item, &mut name, MacroKind::Derive, cx)
-            }
-            ItemKind::Macro(_, _, _) => todo!("Handle macros with multiple kinds"),
+            ItemKind::Macro(_, macro_def, kinds) => match kinds {
+                MacroKinds::BANG => MacroItem(
+                    Macro {
+                        source: display_macro_source(cx, name, macro_def),
+                        macro_rules: macro_def.macro_rules,
+                    },
+                    None,
+                ),
+                MacroKinds::ATTR => clean_proc_macro(item, &mut name, MacroKind::Attr, cx),
+                MacroKinds::DERIVE => clean_proc_macro(item, &mut name, MacroKind::Derive, cx),
+                _ => MacroItem(
+                    Macro {
+                        source: display_macro_source(cx, name, macro_def),
+                        macro_rules: macro_def.macro_rules,
+                    },
+                    Some(kinds),
+                ),
+            },
             // proc macros can have a name set by attributes
             ItemKind::Fn { ref sig, generics, body: body_id, .. } => {
                 clean_fn_or_proc_macro(item, sig, generics, body_id, &mut name, cx)

src/librustdoc/clean/types.rs

@@ -9,7 +9,7 @@ use rustc_abi::{ExternAbi, VariantIdx};
 use rustc_data_structures::fx::{FxHashSet, FxIndexMap, FxIndexSet};
 use rustc_data_structures::thin_vec::ThinVec;
 use rustc_hir::attrs::{AttributeKind, DeprecatedSince, Deprecation};
-use rustc_hir::def::{CtorKind, DefKind, Res};
+use rustc_hir::def::{CtorKind, DefKind, MacroKinds, Res};
 use rustc_hir::def_id::{CrateNum, DefId, LOCAL_CRATE, LocalDefId};
 use rustc_hir::lang_items::LangItem;
 use rustc_hir::{BodyId, ConstStability, Mutability, Stability, StableSince, find_attr};
@@ -664,6 +664,24 @@ impl Item {
         find_attr!(&self.attrs.other_attrs, AttributeKind::NonExhaustive(..))
     }
 
+    pub(crate) fn bang_macro_types(&self) -> Option<Vec<ItemType>> {
+        match self.kind {
+            ItemKind::MacroItem(_, None) => Some(vec![ItemType::Macro]),
+            ItemKind::MacroItem(_, Some(kinds)) => Some(
+                kinds
+                    .iter()
+                    .map(|kind| match kind {
+                        MacroKinds::BANG => ItemType::Macro,
+                        MacroKinds::ATTR => ItemType::ProcAttribute,
+                        MacroKinds::DERIVE => ItemType::ProcDerive,
+                        _ => panic!("unexpected macro kind {kind:?}"),
+                    })
+                    .collect::<Vec<_>>(),
+            ),
+            _ => None,
+        }
+    }
+
     /// Returns a documentation-level item type from the item.
     pub(crate) fn type_(&self) -> ItemType {
         ItemType::from(self)
@@ -834,7 +852,7 @@ pub(crate) enum ItemKind {
     ForeignStaticItem(Static, hir::Safety),
     /// `type`s from an extern block
     ForeignTypeItem,
-    MacroItem(Macro),
+    MacroItem(Macro, Option<MacroKinds>),
     ProcMacroItem(ProcMacro),
     PrimitiveItem(PrimitiveType),
     /// A required associated constant in a trait declaration.
@@ -889,7 +907,7 @@ impl ItemKind {
             | ForeignFunctionItem(_, _)
             | ForeignStaticItem(_, _)
             | ForeignTypeItem
-            | MacroItem(_)
+            | MacroItem(..)
             | ProcMacroItem(_)
             | PrimitiveItem(_)
             | RequiredAssocConstItem(..)

src/librustdoc/fold.rs

@@ -88,7 +88,7 @@ pub(crate) trait DocFolder: Sized {
             | ForeignFunctionItem(..)
             | ForeignStaticItem(..)
             | ForeignTypeItem
-            | MacroItem(_)
+            | MacroItem(..)
             | ProcMacroItem(_)
             | PrimitiveItem(_)
             | RequiredAssocConstItem(..)

src/librustdoc/html/render/context.rs

@@ -13,6 +13,7 @@ use rustc_middle::ty::TyCtxt;
 use rustc_session::Session;
 use rustc_span::edition::Edition;
 use rustc_span::{BytePos, FileName, Symbol, sym};
+use serde::ser::SerializeSeq;
 use tracing::info;
 
 use super::print_item::{full_path, print_item, print_item_path};
@@ -166,6 +167,27 @@ impl SharedContext<'_> {
     }
 }
 
+struct SidebarItem {
+    name: String,
+    is_actually_macro: bool,
+}
+
+impl serde::Serialize for SidebarItem {
+    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+    where
+        S: serde::Serializer,
+    {
+        if self.is_actually_macro {
+            let mut seq = serializer.serialize_seq(Some(2))?;
+            seq.serialize_element(&self.name)?;
+            seq.serialize_element(&1)?;
+            seq.end()
+        } else {
+            serializer.serialize_some(&Some(&self.name))
+        }
+    }
+}
+
 impl<'tcx> Context<'tcx> {
     pub(crate) fn tcx(&self) -> TyCtxt<'tcx> {
         self.shared.tcx
@@ -306,7 +328,20 @@ impl<'tcx> Context<'tcx> {
     }
 
     /// Construct a map of items shown in the sidebar to a plain-text summary of their docs.
-    fn build_sidebar_items(&self, m: &clean::Module) -> BTreeMap<String, Vec<String>> {
+    fn build_sidebar_items(&self, m: &clean::Module) -> BTreeMap<String, Vec<SidebarItem>> {
+        fn build_sidebar_items_inner(
+            name: Symbol,
+            type_: ItemType,
+            map: &mut BTreeMap<String, Vec<SidebarItem>>,
+            inserted: &mut FxHashMap<ItemType, FxHashSet<Symbol>>,
+            is_actually_macro: bool,
+        ) {
+            if inserted.entry(type_).or_default().insert(name) {
+                let type_ = type_.to_string();
+                let name = name.to_string();
+                map.entry(type_).or_default().push(SidebarItem { name, is_actually_macro });
+            }
+        }
         // BTreeMap instead of HashMap to get a sorted output
         let mut map: BTreeMap<_, Vec<_>> = BTreeMap::new();
         let mut inserted: FxHashMap<ItemType, FxHashSet<Symbol>> = FxHashMap::default();
@@ -315,23 +350,24 @@ impl<'tcx> Context<'tcx> {
             if item.is_stripped() {
                 continue;
             }
-
-            let short = item.type_();
-            let myname = match item.name {
+            let name = match item.name {
                 None => continue,
                 Some(s) => s,
             };
-            if inserted.entry(short).or_default().insert(myname) {
-                let short = short.to_string();
-                let myname = myname.to_string();
-                map.entry(short).or_default().push(myname);
+
+            if let Some(types) = item.bang_macro_types() {
+                for type_ in types {
+                    build_sidebar_items_inner(name, type_, &mut map, &mut inserted, true);
+                }
+            } else {
+                build_sidebar_items_inner(name, item.type_(), &mut map, &mut inserted, false);
             }
         }
 
         match self.shared.module_sorting {
             ModuleSorting::Alphabetical => {
                 for items in map.values_mut() {
-                    items.sort();
+                    items.sort_by(|a, b| a.name.cmp(&b.name));
                 }
             }
             ModuleSorting::DeclarationOrder => {}
@@ -864,7 +900,11 @@ impl<'tcx> FormatRenderer<'tcx> for Context<'tcx> {
             self.shared.fs.write(joint_dst, buf)?;
 
             if !self.info.render_redirect_pages {
-                self.shared.all.borrow_mut().append(full_path(self, item), &item_type);
+                self.shared.all.borrow_mut().append(
+                    full_path(self, item),
+                    &item_type,
+                    item.bang_macro_types(),
+                );
             }
             // If the item is a macro, redirect from the old macro URL (with !)
             // to the new one (without).

src/librustdoc/html/render/mod.rs

@@ -505,33 +505,46 @@ impl AllTypes {
         }
     }
 
-    fn append(&mut self, item_name: String, item_type: &ItemType) {
+    fn append(
+        &mut self,
+        item_name: String,
+        item_type: &ItemType,
+        extra_types: Option<Vec<ItemType>>,
+    ) {
         let mut url: Vec<_> = item_name.split("::").skip(1).collect();
         if let Some(name) = url.pop() {
             let new_url = format!("{}/{item_type}.{name}.html", url.join("/"));
             url.push(name);
             let name = url.join("::");
-            match *item_type {
-                ItemType::Struct => self.structs.insert(ItemEntry::new(new_url, name)),
-                ItemType::Enum => self.enums.insert(ItemEntry::new(new_url, name)),
-                ItemType::Union => self.unions.insert(ItemEntry::new(new_url, name)),
-                ItemType::Primitive => self.primitives.insert(ItemEntry::new(new_url, name)),
-                ItemType::Trait => self.traits.insert(ItemEntry::new(new_url, name)),
-                ItemType::Macro => self.macros.insert(ItemEntry::new(new_url, name)),
-                ItemType::Function => self.functions.insert(ItemEntry::new(new_url, name)),
-                ItemType::TypeAlias => self.type_aliases.insert(ItemEntry::new(new_url, name)),
-                ItemType::Static => self.statics.insert(ItemEntry::new(new_url, name)),
-                ItemType::Constant => self.constants.insert(ItemEntry::new(new_url, name)),
-                ItemType::ProcAttribute => {
-                    self.attribute_macros.insert(ItemEntry::new(new_url, name))
+            if let Some(extra_types) = extra_types {
+                for extra_type in extra_types {
+                    self.append_with_url(name.clone(), &extra_type, new_url.clone());
                 }
-                ItemType::ProcDerive => self.derive_macros.insert(ItemEntry::new(new_url, name)),
-                ItemType::TraitAlias => self.trait_aliases.insert(ItemEntry::new(new_url, name)),
-                _ => true,
-            };
+            } else {
+                self.append_with_url(name, item_type, new_url);
+            }
         }
     }
 
+    fn append_with_url(&mut self, name: String, item_type: &ItemType, url: String) {
+        match *item_type {
+            ItemType::Struct => self.structs.insert(ItemEntry::new(url, name)),
+            ItemType::Enum => self.enums.insert(ItemEntry::new(url, name)),
+            ItemType::Union => self.unions.insert(ItemEntry::new(url, name)),
+            ItemType::Primitive => self.primitives.insert(ItemEntry::new(url, name)),
+            ItemType::Trait => self.traits.insert(ItemEntry::new(url, name)),
+            ItemType::Macro => self.macros.insert(ItemEntry::new(url, name)),
+            ItemType::Function => self.functions.insert(ItemEntry::new(url, name)),
+            ItemType::TypeAlias => self.type_aliases.insert(ItemEntry::new(url, name)),
+            ItemType::Static => self.statics.insert(ItemEntry::new(url, name)),
+            ItemType::Constant => self.constants.insert(ItemEntry::new(url, name)),
+            ItemType::ProcAttribute => self.attribute_macros.insert(ItemEntry::new(url, name)),
+            ItemType::ProcDerive => self.derive_macros.insert(ItemEntry::new(url, name)),
+            ItemType::TraitAlias => self.trait_aliases.insert(ItemEntry::new(url, name)),
+            _ => true,
+        };
+    }
+
     fn item_sections(&self) -> FxHashSet<ItemSection> {
         let mut sections = FxHashSet::default();