[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


+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?

This definitely needs a comment, or a better name, that explains more specifically what it is. Without it, I have no way to tell short of examining where it's used to figure out what it is.

I did both. :)

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

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 ?

Fair enough, it'll simply move some checks later on.

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

src/librustdoc/clean/types.rs

    /// `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.

src/librustdoc/clean/types.rs

src/librustdoc/html/render/print_item.rs

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.

The idea is for these macros to show up if we filter on attribute macros or on derive macros as that's what they actually are (among potentially other things).

src/librustdoc/json/conversions.rs

lolbinarycat · 2025-08-21T17:07:14Z

@rustbot author

rustbot · 2025-09-09T15:14:21Z

This PR was rebased onto a different master commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

GuillaumeGomez · 2025-09-09T17:20:03Z

@rustbot ready

bors · 2025-09-27T19:49:31Z

☔ The latest upstream changes (presumably #138907) made this pull request unmergeable. Please resolve the merge conflicts.

rustbot assigned notriddle Aug 15, 2025

lolbinarycat reviewed Aug 16, 2025

View reviewed changes

aDotInTheVoid reviewed Aug 19, 2025

View reviewed changes

src/librustdoc/json/conversions.rs Outdated Show resolved Hide resolved

rustbot added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Aug 21, 2025

GuillaumeGomez added 3 commits September 9, 2025 16:15

Support new bang macro kinds in rustdoc

c75101e

Add tests for attribute bang macros in rustdoc

fe2f898

Use ItemKind placeholders for alternative macro kinds

ec20f2b

GuillaumeGomez force-pushed the rustdoc-bang-attr-macro branch from e173857 to 08c5d0c Compare September 9, 2025 15:14

Deduplicate "attributes" and "attribute macros" sections IDs

c3bcb80

GuillaumeGomez force-pushed the rustdoc-bang-attr-macro branch from 08c5d0c to ac60bd4 Compare September 9, 2025 15:18

This comment has been minimized.

Sign in to view

Improve code and apply suggestions

8729f78

GuillaumeGomez force-pushed the rustdoc-bang-attr-macro branch from ac60bd4 to 8729f78 Compare September 9, 2025 15:46

rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Sep 9, 2025

[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 by lolbinarycat 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!

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!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

lolbinarycat commented Aug 21, 2025

Uh oh!

rustbot commented Sep 9, 2025

Uh oh!

This comment has been minimized.

GuillaumeGomez commented Sep 9, 2025

Uh oh!

bors commented Sep 27, 2025

Uh oh!

Uh oh!

GuillaumeGomez commented Aug 15, 2025 •

edited by lolbinarycat

Loading