feat: support macro expansion in #[doc = ...] attributes

[so1ve]

fixes #7688, fixes #8092, fixes #11137, fixes #20494, closes #21303

Macro expansion part is hand-written; AI (specifically, GPT 5.4) was used to generate tests.

[rustbot]

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.

[ChayimFriedman2]

I cannot vouch for which is better but note that #21303 also implements that however by text-matching on include_str!() and supporting it alone. Does this PR does the same, or does it fully expand all macros?

[so1ve]

Yes, this PR uses rust-analyzer's internal macro expansion mechanism, enabling all macro expansion within #[doc] attributes, instead of special-casing include_str. See this test case for details.

[ChayimFriedman2]

Then this PR is preferred.

[ChayimFriedman2]

Good work!

View changes since this review

[so1ve]

Just applied the suggestions!

[ChayimFriedman2]

I'm really sorry, but it looks like even outer doc comments in module resolve inside the module (https://play.rust-lang.org/?version=stable&mode=debug&edition=2024&gist=a98e60abf9c8b018f0d47ed687c7416e). Which is very weird IMO (unintended behavior?) but we should follow rustc 😅

View changes since this review

[so1ve]

Updated!

[ChayimFriedman2]

Many thanks!

I have an idea what to do with cfg_attr, I'll do it later.

View changes since this review

[asukaminato0721]

amazing!

[lnicola]

Unlike #21303, this didn't add .md to the included extensions, so many of the linked issues and even the test won't work.

Should we bite the bullet and load those into the VFS?

[Veykril]

Yea I think we should

[ChayimFriedman2]

There aren't many markdown files usually so I believe it shouldn't cause perf problems.

[lnicola]

@asukaminato0721 want to do the honors? :)

[so1ve]

Ah, I never considered that the expansion of include_str requires the use of the VFS 😅 I was misled by the test, it seems that include_str in the test can run normally

[ChayimFriedman2]

Tests always includes the specified files in the VFS.

[asukaminato0721]

@asukaminato0721 want to do the honors? :)

sure :)

[joshka]

This does not appear to actually work (for the axum source code at least).

It does not appear to have fixed the problem:

Installed version:

https://github.com/tokio-rs/axum/blob/441216428893d13544f12722b54dcaaadd47135a/axum/src/error_handling/mod.rs#L1
Module level doc:

Function level doc:
https://github.com/tokio-rs/axum/blob/441216428893d13544f12722b54dcaaadd47135a/axum/src/routing/method_routing.rs#L1002

I'd recommend re-opening at least one of the mentioned issues to track this (and perhaps consolidating on one of them?)

[ChayimFriedman2]

@joshka As explained literally just above, the expansion does work but rust-analyzer in its current version does not load md files. If you'll make the file extension .rs it'll work. This will be fixed by the next release.

[joshka]

Ah, I see now. I missed that the VFS piece meant markdown wouldn’t work yet. Thanks for clarifying.