Rustdoc bang attr macro by GuillaumeGomez · Pull Request #152449 · rust-lang/rust

GuillaumeGomez · 2026-02-10T18:09:21Z

Since it seems like I can't reopen #145458, opening this one. Although, it's the same PR minus the last new commit to handle a comment that was left unresolved in the original PR. All relevant details are still in the original PR though.

It's an alternative (and likely a take-over) of #148005 since lang-team rejected the idea to add documentation on macro branches, making the multiple files approach less suitable.

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.

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.

From RFCs:

derive:

attr:

both:

r? @notriddle

rustbot · 2026-02-10T18:09:24Z

Some changes occurred in HTML/CSS/JS.

cc @lolbinarycat

GuillaumeGomez · 2026-02-10T20:25:32Z

Oh and also cc @lolbinarycat as you reviewed the original PR too. :)

GuillaumeGomez · 2026-02-20T12:05:34Z

Fixed merge conflicts.

lolbinarycat · 2026-04-06T19:27:23Z

blocking this on #154902, since that relies on bang macro === macro_rules macro.

GuillaumeGomez · 2026-04-18T20:18:09Z

Ready for review.

lolbinarycat

After reading through everything it seems there's still some level of conflation between declarative (macro_rules! and v2 macros) and procedural macros.

I still feel like our data model for macros is a bit of a mess, and there doesn't seem to be a clear vision of what the desired end state is, at least not one I have access to.

The search handling I'm also unsure about the design of. Remember we have itemParents now, that could be useful here.

I also worry about if cross-crate inlining breaks any of this stuff. In general, I think the test coverage is a bit lacking, there are only 7 potential cases¹, but not a single test suite covers all of them.

View changes since this review

I guess doubled to 14 if you want to do all of them through cross-crate reexports too ↩

lolbinarycat · 2026-04-22T19:06:26Z

+                MacroKinds::ATTR => clean_proc_macro(item, &mut name, MacroKind::Attr, cx.tcx),
+                MacroKinds::DERIVE => clean_proc_macro(item, &mut name, MacroKind::Derive, cx.tcx),


I think this is wrong, a macro_rules! macro should be able to go into this branch, which does not seem ideal.

Do we really not have a way of just... checking if something is a proc macro or not? can clean_proc_macro handle being given a non-proc macro?

In this case, if macro_rules! containing only an attr or a derive, we treat them the same as their proc-macro equivalent.

is that the desired behavior? it seems somewhat odd.

Yep it is. :)

lolbinarycat · 2026-04-22T19:12:41Z

+    BangMacroAttribute = 28,
+    BangMacroDerive = 29,


These feel like misnomers, a "bang macro" generally refers to a fn-like macro, called with !(), not just anything declared with macro_rules!. also could definitely benefit from doc comments.

It's about how they're declared, not how they're used. Big +1 for the missing docs, adding that.

problem is that's not what "bang macro" conventionally means, and i would rather not introduce more instances of "this term is used completely differently within rustdoc".

i would prefer we just use "DeclMaro", as both of these can be grouped under "declarative macros"

Sounds good to me.

lolbinarycat · 2026-04-22T21:30:42Z

-            block("attr", "attributes", "Attribute Macros");
+            block("attr", "attribute-macros", "Attribute Macros");


Once again, not a fan of bugfixes that break links being buried within a larger change like this.

Needed for tests.

ah... it might be better to rename the other block, as that should break drastically less links

That's a very good point. Switching the change between the two then.

lolbinarycat · 2026-04-22T21:32:06Z

+         * But the documentation lives in a single `macro.NAME.html` page, and
+         * this boolean flag is used for generating that HREF.
+         */
+        isBangMacro: boolean,


I really don't like this field name.

Open to suggestions. :)

the problem is the current semantics are "is this a non-proc macro that is usable in multiple ways or is fn-like"

i think naming it based on purpose rather than on definition would be good, so forceMacroHref.

Sounds good to me!

lolbinarycat · 2026-04-22T21:36:29Z

+        if (item.ty === 28 || item.ty === 29) {
+            // "proc attribute" is 23, "proc derive" is 24 whereas "bang macro attribute" is 28 and
+            // "bang macro derive" is 29, so 5 of difference to go from the latter to the former.
+            item.ty -= 5;
+            item.isBangMacro = true;
+        }
+        return item;


ah, so this is the point of adding those two enum variants...

I do wonder if there's a better way to encode this...

Likely not but very interested if you have ideas.

we could overload the last field even more x3

lolbinarycat · 2026-04-22T21:39:55Z

            let href;
            let traitPath = null;
-            const type = itemTypesName[item.ty];
+            const type = item.entry && item.entry.isBangMacro ? "macro" : itemTypesName[item.ty];


so, these hybrid macros will show up with attr: and derive: searches but will have macro in the url? seems confusing.

That's the whole debate we had 2 rustdoc meetings ago. The alternative was to have a file for each kind of the macro but this approach was rejected.

derive and attr are children of macro, so it should be fine.

lolbinarycat · 2026-04-22T21:42:56Z

+/// An attribute bang macro.
+#[macro_export]
+macro_rules! attr_macro {
+    attr() () => {};
+    () => {};
+}
+
+/// A derive bang macro.
+#[macro_export]
+macro_rules! derive_macro {
+    derive() () => {};
+    () => {};
+}
+
+#[macro_export]
+macro_rules! one_for_all_macro {
+    attr() () => {};
+    derive() () => {};
+    () => {};
+}


what about something of the shape of:

#[macro_export] macro_rules! attr_macro { attr() () => {}; }

or

#[macro_export] macro_rules! one_for_all_macro { attr() () => {}; derive() () => {}; }

I suspect the former may show up as a proc macro.

I confirm it would. Adding a test to cover them.

Ah it's already tested in tests/rustdoc-html/macro/macro-attr.rs actually. :)

GuillaumeGomez · 2026-04-23T20:53:52Z

Went through all comments and pushed improvements and suggestions (and a new test). So if I didn't miss anything, only tests missing are for cross-crate, right?

GuillaumeGomez · 2026-04-24T01:27:17Z

The debug_assert_matches I added were too strict on the matching, so I relaxed them a bit. But still a super good idea. :)

Rename `ItemType::BangMacro*` into `ItemType::DeclMacro*` Rename `isBangMacro` field into `forceMacroHref`

rustbot · 2026-04-27T15:56:22Z

This PR was rebased onto a different main 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 · 2026-04-27T15:57:25Z

Updated ItemType variants name, updated the ID so attribute macros keep attributes and renamed the field.

rustbot assigned notriddle Feb 10, 2026