[rustdoc] Add support new bang macro kinds #145458

GuillaumeGomez · 2025-08-15T15:49:05Z

This implements #145153 in rustdoc. This PR voluntarily doesn't touch anything related to intra-doc links, I'll send a follow-up if needed.

So now about the implementation itself: this is a weird case where a macro can be different things at once but still only gets one file generated. I saw two ways to implement this:

Handle ItemKind::Macro differently and iter through its MacroKinds values.
Add new placeholder variants in the ItemKind enum, which means that when we encounter them in rendering, we need to ignore them. It also makes the ItemKind enum bigger (and also needs more code to be handled). Another downside is that it needs to be handled in the JSON output.

I implemented 1. in the first commit and 2. in the third commit so if we don't to keep 2., I can simply remove it. I personally have no preference for one or the other since the first is "simpler" but it's easy to forget to go through the macro kinds whereas the second needs a lot more code.

Now there was an interesting improvement that came with this PR in the html::render::print_item::item_module function: I simplified its implementation and split the different parts in a HashMap where the key is the item type. So then, we can just iterate through the keys and open/close the section at each iteration instead of keeping an Option<section> around.

cc @joshtriplett

rustbot · 2025-08-15T15:49:10Z

r? @notriddle

rustbot has assigned @notriddle.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

rustbot · 2025-08-15T15:49:13Z

Some changes occurred in HTML/CSS/JS.

cc @GuillaumeGomez, @jsha, @lolbinarycat

lolbinarycat

I can't really say much about the actual logic correctness (it seems mostly fine?), but i do have a few nitpicks about naming, datatype structure and logic clarity.

It was also a bit weird reviewing this with the two alternate implementations, since as far as I can tell there's a few lines of code that are common between both impls, but actually have different semantics between them.

lolbinarycat · 2025-08-16T15:27:16Z

src/librustdoc/html/render/context.rs

@@ -163,6 +164,27 @@ impl SharedContext<'_> {
    }
 }

+struct SidebarItem {
+    name: String,
+    is_actually_macro: bool,


Unclear what "actually" means here, is it possible for a sidebar item to be a macro, but not actually be a macro?

I think this should probably be renamed to is_decl_macro or is_macro_rules, or maybe is_macro_placeholder?

lolbinarycat · 2025-08-16T15:46:37Z

src/librustdoc/html/static/js/main.js

+            for (const item of filtered) {
+                let name = item;
+                let isMacro = false;
+                if (Array.isArray(item)) {
+                    name = item[0];
+                    isMacro = true;
+                }


I believe Window.SIDEBAR_ITEMS in rustdoc.d.ts should now have type { [key: string]: (string | [string, 1])[] }, and the previous @ts-expect-error should be able to be converted to a nonnull call?

lolbinarycat · 2025-08-16T16:00:01Z

src/librustdoc/clean/mod.rs

+                        source: display_macro_source(cx, name, macro_def),
+                        macro_rules: macro_def.macro_rules,
+                    },
+                    None,


Why None and not just MacroKinds::BANG ?

lolbinarycat · 2025-08-16T16:07:36Z

src/librustdoc/clean/types.rs

@@ -924,7 +942,7 @@ pub(crate) enum ItemKind {
    ForeignStaticItem(Static, hir::Safety),
    /// `type`s from an extern block
    ForeignTypeItem,
-    MacroItem(Macro),
+    MacroItem(Macro, Option<MacroKinds>),


I don't like the use of Option here, for two reasons:

MacroKinds::empty() already can represent the absence of any value

what None actually represents here is MacroKinds::BANG

I think the rationale for the second is that this represents extra macro kinds, but I think the use of Option is still unnecessary, as it leaves MacroKinds::empty() as a meaningless value that should never be used, which seems like something we would want to avoid.

lolbinarycat · 2025-08-16T16:23:24Z

src/librustdoc/clean/types.rs

+    AttrMacroItem,
+    DeriveMacroItem,


I feel like these should at the very least have a doc comment saying these are for non-proc macros.

lolbinarycat · 2025-08-16T16:56:02Z

src/librustdoc/html/render/print_item.rs

+            let tag =
+                if section_id == "reexports" { REEXPORTS_TABLE_OPEN } else { ITEM_TABLE_OPEN };


We have an ItemSection as my_section, please compare that with ItemSection::Reexport instead of doing typo-prone (and possibly slower) string comparison.

lolbinarycat · 2025-08-16T17:01:52Z

src/librustdoc/formats/item_type.rs

+            // Is this a good idea?
+            clean::AttrMacroItem => ItemType::ProcAttribute,
+            // Is this a good idea?
+            clean::DeriveMacroItem => ItemType::ProcDerive,


It seems fairly confusing to me, I don't see the advantage (is it so item_module groups things correctly? if that's the case, then the first commit on its own would not be correct, since it would categorize these macros as ItemType::Macro), and it already causes a bit of weirdness in html_filename which would not be needed if these were categorized as Macro instead.

if we did want to make this change, I would at least want to change the names of the item types to not imply they must be derives.

aDotInTheVoid · 2025-08-19T23:26:10Z

src/librustdoc/json/conversions.rs

-        MacroItem(m) => ItemEnum::Macro(m.source.clone()),
+        MacroItem(m, _) => ItemEnum::Macro(m.source.clone()),
+        // They are just placeholders so no need to handle them.
+        AttrMacroItem | DeriveMacroItem => return None,


We should handle these like KeywordItem, and return None from them earlier, so that from_clean_item can remain a total function (and not return an Option).

GuillaumeGomez added 3 commits August 15, 2025 17:00

Support new bang macro kinds in rustdoc

3552177

Add tests for attribute bang macros in rustdoc

07871bd

Use ItemKind placeholders for alternative macro kinds

e173857

rustbot assigned notriddle Aug 15, 2025

lolbinarycat reviewed Aug 16, 2025

View reviewed changes

aDotInTheVoid reviewed Aug 19, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[rustdoc] Add support new bang macro kinds #145458

[rustdoc] Add support new bang macro kinds #145458

GuillaumeGomez commented Aug 15, 2025 •

edited

Loading

Uh oh!

rustbot commented Aug 15, 2025

Uh oh!

rustbot commented Aug 15, 2025

Uh oh!

lolbinarycat left a comment

Uh oh!

lolbinarycat Aug 16, 2025

Uh oh!

lolbinarycat Aug 16, 2025

Uh oh!

lolbinarycat Aug 16, 2025

Uh oh!

lolbinarycat Aug 16, 2025

Uh oh!

lolbinarycat Aug 16, 2025

Uh oh!

lolbinarycat Aug 16, 2025

Uh oh!

lolbinarycat Aug 16, 2025

Uh oh!

aDotInTheVoid Aug 19, 2025

Uh oh!

Uh oh!

		let tag =
		if section_id == "reexports" { REEXPORTS_TABLE_OPEN } else { ITEM_TABLE_OPEN };

[rustdoc] Add support new bang macro kinds #145458

Are you sure you want to change the base?

[rustdoc] Add support new bang macro kinds #145458

Conversation

GuillaumeGomez commented Aug 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rustbot commented Aug 15, 2025

Uh oh!

rustbot commented Aug 15, 2025

Uh oh!

lolbinarycat left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

GuillaumeGomez commented Aug 15, 2025 •

edited

Loading