rustdoc: add support for macro_rules macros of multiple kinds #148005

notriddle · 2025-10-22T22:38:01Z

This adds support for advanced RFC 3697 and 3698 macros, that look like this:

/// Doc Comment.
macro_rules! NAME {
    attr(key = $value:literal) ($attached:item) => { ... };
    derive() ($attached:item) => { ... };
    ($bang:tt) => { ... };
}

And can be used like this:

/*attr*/ #[NAME]
/*derive*/ #[derive(NAME)]
/*bang*/ NAME!{}

The basic problem is that there are three different ways to use this macro, and, historically, these three ways were implemented by fully-separated proc macro items with separate doc comments. We want these new declarative macros to work the same way, so they appear in the same section of the module table of contents and can be filtered for in the search engine.

This commit makes the feature work by generating separate pages for each macro kind. These separate pages appear in separate sections of the module table of contents, produce separate search results, and have duplicate copies of the doc comment.

The following features would also be helpful, but are left for future commits to implement:

To improve the produced documentation, we should probably add support for adding /// attributes to macro rules arms, so that the different syntaxes can actually be documented separately.
This commit doesn't test intra-doc links.

Parts of #145458 are directly used in this code.

cc @joshtriplett @GuillaumeGomez @lolbinarycat

This adds support for advanced RFC 3697 and 3698 macros, that look like this: ``` /// Doc Comment. macro_rules! NAME { attr(key = $value:literal) ($attached:item) => { ... }; derive() ($attached:item) => { ... }; ($bang:tt) => { ... }; } ``` And can be used like this: ``` /*attr*/ #[NAME] /*derive*/ #[derive(NAME)] /*bang*/ NAME!{} ``` The basic problem is that there are three different ways to use this macro, and, historically, these three ways were implemented by fully-separated proc macro items with separate doc comments. We want these new declarative macros to work the same way, so they appear in the same section of the module table of contents and can be filtered for in the search engine. This commit makes the feature work by generating separate pages for each macro kind. These separate pages appear in separate sections of the module table of contents, produce separate search results, and have duplicate copies of the doc comment. The following features would also be helpful, but are left for future commits to implement: - To improve the produced documentation, we should probably add support for adding `///` attributes to macro rules arms, so that the different syntaxes can actually be documented separately. - This commit doesn't test intra-doc links. Parts of rust-lang#145458 are directly used in this code. Co-Authored-By: Guillaume Gomez <[email protected]>

GuillaumeGomez · 2025-10-23T10:20:49Z

Although I find the result of this approach less good (ie, duplicated files generated for the same macro), considering how much easier the implementation is, I'd prefer for this one to be merged. I'll close #145458.

GuillaumeGomez · 2025-10-23T10:22:22Z

Btw, the PR looks ready to me so feel free to r=me unless you want to make more changes.

rustbot · 2025-10-23T16:09:57Z

rustdoc-json-types is a public (although nightly-only) API. If possible, consider changing src/librustdoc/json/conversions.rs; otherwise, make sure you bump the FORMAT_VERSION constant.

cc @CraftSpider, @aDotInTheVoid, @Enselic, @obi1kenobi

Some changes occurred in GUI tests.

cc @GuillaumeGomez

Some changes occurred in HTML/CSS/JS.

cc @GuillaumeGomez, @jsha, @lolbinarycat

rustbot · 2025-10-23T16:10:00Z

r? @GuillaumeGomez

rustbot has assigned @GuillaumeGomez.
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

notriddle · 2025-10-23T16:58:07Z

r? @lolbinarycat

I know you have already looked at the code a little bit. Can you check it and make sure I'm using the bitflags correctly?

…triddle [rustdoc] Include attribute and derive macros when filtering on "macros" As discussed [here](rust-lang#147909), some filters should have been "grouped". This PR allows attribute and derive macros to match the `macro` filter. I'll wait for rust-lang#148005 to add more tests as it would require a proc-macro library for now. r? `@notriddle`

…triddle [rustdoc] Include attribute and derive macros when filtering on "macros" As discussed [here](rust-lang#147909), some filters should have been "grouped". This PR allows attribute and derive macros to match the `macro` filter. I'll wait for rust-lang#148005 to add more tests as it would require a proc-macro library for now. r? ``@notriddle``

…triddle [rustdoc] Include attribute and derive macros when filtering on "macros" As discussed [here](rust-lang#147909), some filters should have been "grouped". This PR allows attribute and derive macros to match the `macro` filter. I'll wait for rust-lang#148005 to add more tests as it would require a proc-macro library for now. r? ```@notriddle```

Rollup merge of #148176 - GuillaumeGomez:filter-macros, r=notriddle [rustdoc] Include attribute and derive macros when filtering on "macros" As discussed [here](#147909), some filters should have been "grouped". This PR allows attribute and derive macros to match the `macro` filter. I'll wait for #148005 to add more tests as it would require a proc-macro library for now. r? ```@notriddle```

[rustdoc] Include attribute and derive macros when filtering on "macros" As discussed [here](rust-lang/rust#147909), some filters should have been "grouped". This PR allows attribute and derive macros to match the `macro` filter. I'll wait for rust-lang/rust#148005 to add more tests as it would require a proc-macro library for now. r? ```@notriddle```

lolbinarycat · 2025-11-05T20:55:30Z

src/librustdoc/clean/inline.rs

+                        unreachable!("Iterating over macro kinds always yields one kind at a time")
+                    }
+                };
+                record_extern_fqn(cx, did, type_kind);


I think we should have a comment noting the fact that we create multiple (pages? search index entries? something else?) for macros that are of multiple kinds, since it's a somewhat unexpected behavior.

lolbinarycat · 2025-11-05T20:56:23Z

src/librustdoc/clean/inline.rs

+                    match mac_kind {
+                        MacroKinds::BANG => MacroKind::Bang,
+                        MacroKinds::ATTR => MacroKind::Attr,
+                        MacroKinds::DERIVE => MacroKind::Derive,
+                        _ => unreachable!(
+                            "Iterating over macro kinds always yields one kind at a time"
+                        ),
+                    },
+                );
+                let type_kind = match mac_kind {
+                    MacroKinds::BANG => ItemType::Macro,
+                    MacroKinds::ATTR => ItemType::MacroAttribute,
+                    MacroKinds::DERIVE => ItemType::MacroDerive,
+                    _ => {
+                        unreachable!("Iterating over macro kinds always yields one kind at a time")
+                    }
+                };


nit: These two match statements could be merged into one that returns a tuple.

lolbinarycat · 2025-11-05T21:16:43Z

src/librustdoc/formats/item_type.rs

+            DefKind::Macro(kinds) if kinds == MacroKinds::ATTR | MacroKinds::DERIVE => {
+                &[ItemType::MacroAttribute, ItemType::MacroDerive]
+            }
+            DefKind::Macro(kinds) if kinds == MacroKinds::ATTR | MacroKinds::BANG => {
+                &[ItemType::Macro, ItemType::MacroAttribute]
+            }
+            DefKind::Macro(kinds) if kinds == MacroKinds::DERIVE | MacroKinds::BANG => {
+                &[ItemType::Macro, ItemType::MacroDerive]
+            }
+            DefKind::Macro(kinds)
+                if kinds == MacroKinds::BANG | MacroKinds::ATTR | MacroKinds::DERIVE =>
+            {
+                &[ItemType::Macro, ItemType::MacroAttribute, ItemType::MacroDerive]
+            }
+            DefKind::Macro(kinds) => unimplemented!("unsupported macro kinds {kinds:?}"),


Code like this makes me really wish we were using enumset instead.

lolbinarycat · 2025-11-05T21:25:45Z

src/librustdoc/html/format.rs


    let def_kind = tcx.def_kind(def_id);
-    let shortty = def_kind.into();
+    let shortty = ItemType::from_def_kind(def_kind, None)[0];


This means that href_with_root_path will always link to the same page, regardless of context, is this what we want?

lolbinarycat · 2025-11-05T21:26:19Z

@rustbot author

rustbot · 2025-11-05T21:26:24Z

Reminder, once the PR becomes ready for a review, use @rustbot ready.

obi1kenobi · 2025-11-06T01:12:38Z

(Asking with my cargo-semver-checks hat on, for SemVer linting purposes.)

Am I correct in understanding that with this PR:

the two kinds of derive macros (declarative and procedural) become indistinguishable from each other?
the two kinds of attribute macros also become indistinguishable from each other?

This is somewhat undesirable, because it worsens cargo-semver-checks' ability to accurately describe to the user where their breakage is found.

It's not a breaking change to move procedural derive macro to a declarative derive macro, of course. However:

As a general rule, we can write more lints for declarative macros than for procedural ones, because we can (sometimes, in theory) see the declarative parts and lint them. So being able to differentiate between them in rustdoc JSON is good!
Even ignoring the above, it's still good for our diagnostics to accurately specify whether a macro involved in breakage (e.g. "used to exist but then got deleted") was procedural or declarative.

If it's not a huge lift to do so, it'd be nice to include this information in rustdoc JSON. I'd be happy to review and offer feedback if that'd be helpful.

lolbinarycat · 2025-11-06T01:16:59Z

@obi1kenobi maybe a naive question, but can't you just check if the source crate is a proc_macro crate? or does inlining mess with that?

obi1kenobi · 2025-11-06T01:53:34Z

Honestly, I'm not sure. But I imagine most consumers of rustdoc JSON would want to show users accurate diagnostics on where the item came from, and "here's this one weird trick that works but isn't that discoverable" isn't a great story to tell all of them :) If it's truly that easy, it feels like it's even more of an argument to just include a flag or similar in the JSON.

…triddle [rustdoc] Include attribute and derive macros when filtering on "macros" As discussed [here](rust-lang#147909), some filters should have been "grouped". This PR allows attribute and derive macros to match the `macro` filter. I'll wait for rust-lang#148005 to add more tests as it would require a proc-macro library for now. r? ```@notriddle```

[rustdoc] Include attribute and derive macros when filtering on "macros" As discussed [here](rust-lang/rust#147909), some filters should have been "grouped". This PR allows attribute and derive macros to match the `macro` filter. I'll wait for rust-lang/rust#148005 to add more tests as it would require a proc-macro library for now. r? ```@notriddle```

notriddle · 2025-11-17T00:27:07Z

@obi1kenobi

the two kinds of derive macros (declarative and procedural) become indistinguishable from each other?

As far as I can tell, the only change to the clean->JSON conversion is these lines:

diff --git a/src/librustdoc/json/conversions.rs b/src/librustdoc/json/conversions.rs
index 909262d563e9f..b57f27f529738 100644
--- a/src/librustdoc/json/conversions.rs
+++ b/src/librustdoc/json/conversions.rs
@@ -892,8 +892,8 @@ impl FromClean<ItemType> for ItemKind {
             Keyword => ItemKind::Keyword,
             Attribute => ItemKind::Attribute,
             TraitAlias => ItemKind::TraitAlias,
-            ProcAttribute => ItemKind::ProcAttribute,
-            ProcDerive => ItemKind::ProcDerive,
+            MacroAttribute => ItemKind::ProcAttribute,
+            MacroDerive => ItemKind::ProcDerive,
         }
     }
 }

The code that generates ItemEnum wasn't changed, so the proc macros and declarative macros should still be distinguishable.

obi1kenobi

Broadly LGTM, just some polishing suggestions.

View changes since this review

obi1kenobi · 2025-11-18T01:53:49Z

src/rustdoc-json-types/lib.rs

    /// or `ItemEnum::ProcMacro(ProcMacro { kind: MacroKind::Bang })`
    Macro,
-    /// A procedural macro attribute.
+    /// A macro attribute.


I noticed procedural was deleted here, but was not deleted below in the doc comment for ProcDerive. I found that surprising, is that intentional?

obi1kenobi · 2025-11-18T01:55:22Z

tests/rustdoc-gui/src/test_docs/macros.rs

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


This is great! Would you mind adding a similar test to tests/rustdoc-json, just to make it super obvious how these macros are represented?

Happy to help if you get stuck on the syntax for the checks.

obi1kenobi · 2025-11-18T01:56:25Z

src/rustdoc-json-types/lib.rs

+    /// and `ItemEnum::Macro(_)`; this should probably be renamed.
    ProcAttribute,
    /// A procedural macro usable in the `#[derive()]` attribute.
    ///
    /// Corresponds to `ItemEnum::ProcMacro(ProcMacro { kind: MacroKind::Derive })`
+    /// and `ItemEnum::Macro(_)`; this should probably be renamed.


My 2 cents: go ahead and rename them right now. There's no time like the present, and there's no stability guarantee to worry about in rustdoc JSON. The format is versioned anyway.

Speaking of, remember to bump the version number :)

notriddle mentioned this pull request Oct 22, 2025

[rustdoc] Add support new bang macro kinds #145458

Closed

GuillaumeGomez approved these changes Oct 23, 2025

View reviewed changes

notriddle marked this pull request as ready for review October 23, 2025 16:09

rustbot added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Oct 23, 2025

rustbot removed the S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. label Oct 23, 2025

rustbot assigned GuillaumeGomez Oct 23, 2025

rustbot assigned lolbinarycat and unassigned GuillaumeGomez Oct 23, 2025

notriddle mentioned this pull request Oct 24, 2025

Doc comments and attributes on macro arms rust-lang/compiler-team#935

Open

3 tasks

GuillaumeGomez mentioned this pull request Oct 27, 2025

[rustdoc] Include attribute and derive macros when filtering on "macros" #148176

Merged

lolbinarycat reviewed Nov 5, 2025

View reviewed changes

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 Nov 5, 2025

obi1kenobi reviewed Nov 18, 2025

View reviewed changes

rustdoc: add support for macro_rules macros of multiple kinds #148005

Are you sure you want to change the base?

rustdoc: add support for macro_rules macros of multiple kinds #148005

Uh oh!

Conversation

notriddle commented Oct 22, 2025

Uh oh!

GuillaumeGomez commented Oct 23, 2025

Uh oh!

GuillaumeGomez commented Oct 23, 2025

Uh oh!

rustbot commented Oct 23, 2025

Uh oh!

rustbot commented Oct 23, 2025

Uh oh!

notriddle commented Oct 23, 2025

Uh oh!

lolbinarycat Nov 5, 2025

Choose a reason for hiding this comment

Uh oh!

lolbinarycat Nov 5, 2025

Choose a reason for hiding this comment

Uh oh!

lolbinarycat Nov 5, 2025

Choose a reason for hiding this comment

Uh oh!

lolbinarycat Nov 5, 2025

Choose a reason for hiding this comment

Uh oh!

lolbinarycat commented Nov 5, 2025

Uh oh!

rustbot commented Nov 5, 2025

Uh oh!

obi1kenobi commented Nov 6, 2025

Uh oh!

lolbinarycat commented Nov 6, 2025

Uh oh!

obi1kenobi commented Nov 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

notriddle commented Nov 17, 2025

Uh oh!

obi1kenobi left a comment • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

obi1kenobi Nov 18, 2025

Choose a reason for hiding this comment

Uh oh!

obi1kenobi Nov 18, 2025

Choose a reason for hiding this comment

Uh oh!

obi1kenobi Nov 18, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

obi1kenobi commented Nov 6, 2025 •

edited

Loading

obi1kenobi left a comment •

edited by rustbot

Loading