Skip to content

Conversation

notriddle
Copy link
Contributor

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 <guillaume1.gomez@gmail.com>
@rustbot rustbot added A-rustdoc-json Area: Rustdoc JSON backend A-rustdoc-search Area: Rustdoc's search feature S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. T-rustdoc-frontend Relevant to the rustdoc-frontend team, which will review and decide on the web UI/UX output. labels Oct 22, 2025
@GuillaumeGomez
Copy link
Member

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
Copy link
Member

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

A-rustdoc-json Area: Rustdoc JSON backend A-rustdoc-search Area: Rustdoc's search feature S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. T-rustdoc-frontend Relevant to the rustdoc-frontend team, which will review and decide on the web UI/UX output.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants