macro expansion for the `doc` attribute must occur during the rustdoc pass

[fidelicura]

Code

macro_rules! doc_literal {
    () => {
        "Welcome!"
    };
}

struct Foo {
    #[doc = doc_literal!()]
    bar: usize,
}

Reproduction Steps

cargo build and that's it.

Expected Outcome

This documentation comment is expanded only after the rustdoc has finished it's work, as far as I can see. So, neither LSP can't see this comment, nor clap. This would be really useful when you have multiple places that should have the similar documentation, but stored in a centralized manner.

Actual Output

$ cargo expand
    Checking doc_comment_literal_macro v0.1.0 (/home/me/Desktop/doc_comment_literal_macro)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.08s

#![feature(prelude_import)]
#![allow(unused)]
#[prelude_import]
use std::prelude::rust_2024::*;
#[macro_use]
extern crate std;
struct Foo {
    ///Welcome!
    bar: usize,
}
fn main() {}

Version

$ rustdoc --version
rustdoc 1.87.0 (17067e9ac 2025-05-09)

$ cargo -V
cargo 1.87.0 (99624be96 2025-05-06)

$ rustc -V
rustc 1.87.0 (17067e9ac 2025-05-09)

Additional Details

[bjorn3]

Docs are stored in the crate metadata for public items by rustc in case rustdoc needs them for a dependency. In addition rustc has to already expand the doc attributes because intra-doc links need the name resolver to resolve the target of the link, but once rustdoc runs the name resolver no longer exists.

[bjorn3]

This documentation comment is expanded only after the rustdoc has finished it's work, as far as I can see. So, neither LSP can't see this comment, nor clap. This would be really useful when you have multiple places that should have the similar documentation, but stored in a centralized manner.

Do you mean that this is the actual outcome rather than the expected outcome? Rust-analyzer doesn't currently know how to do macro expansion inside doc attributes. That is a rust-analyzer limitation, not a rust language or rustc limitation. As for clap, it seems that clap simply doesn't recognize #[doc] attributes as doc comment. That is something that would need to be fixed in clap, not rustc.

[fidelicura]

As for clap, it seems that clap simply doesn't recognize #[doc] attributes as doc comment. That is something that would need to be fixed in clap, not rustc.

As far as I can see, clap recognizes and parses #[doc] attributes correctly: https://github.com/clap-rs/clap/blob/4c039309b614ee4523c67a243afc38af11860de9/clap_derive/src/utils/doc_comments.rs#L18.

Also, if I replace the usage of macro with a direct string literal, like this:

struct Foo {
    #[doc = "Welcome!"]
    bar: usize,
}

...it will also be recognized correctly both by rust-analyzer and clap.

[bjorn3]

As far as I can see, clap recognizes and parses #[doc] attributes correctly: https://github.com/clap-rs/clap/blob/4c039309b614ee4523c67a243afc38af11860de9/clap_derive/src/utils/doc_comments.rs#L18.

That only matches #[doc = "..."] not #[doc = foo!()]. When the clap derive macro runs, no macro expansion of the item aside from any #[cfg] has happened yet.

[fidelicura]

@bjorn3, thanks for the explanation! Now I understand that.

You said: "that is something that would need to be fixed in clap, not rustc", is it possible to parse such not expanded macro as if it were expanded?

Also, if it's not too much trouble, are there any ways to inherit or reuse documentation comments without repeating code? (apart from clap)

I think I'll close this issue as I don't see any way to "fix" this.

[bjorn3]

You said: "that is something that would need to be fixed in clap, not rustc", is it possible to parse such not expanded macro as if it were expanded?

It may be possible for clap to preserve the macro invocation and merge all doc comments together using concat!().