rust-analyzer doesn't handle docs on exported proc-macros properly

[sam0x17]

Suppose you have some proc macros, so inevitably you have some sort of inner crate that defines those proc macros and an outer crate that uses the macros from the inner crate:

// inner_crate lib.rs

/// A macro that is mine and does many things
#[proc_macro]
pub fn my_macro(tokens: TokenStream) -> TokenStream {
    ...
}

// outer_crate main.rs

/// See also: [`OurterCrateTrate`], [`outer_crate_function`]
///
pub use inner_crate::my_macro;

A key problem a lot of library authors run into is rust-analyzer will only show the inner_crate docs for my_macro when you hover over any calls to my_macro!, and will completely ignore (not display) any additional doc comments added by re-exports of the macro in the outer crate. This is true even if the only docs for the macro are on the re-export in outer_crate.

Conversely, cargo doc itself will display the "See Also:" comment followed by the original docs for the macro declaration that resides in inner_crate in the outer_crate.

If this behavior were properly handled by rust-analyzer as it is by cargo doc, library authors would have a much easier path in this scenario when there are items in the outer crate that they want to refer to / link to from their proc macro docs -- they could simply not document proc macros at all within the inner crate and do all the documentation in the outer crate.

Unfortunately right now when crates do this, rust-analyzer will show nothing when you hover over one of the macro calls in the outer crate (or crates using the outer crate), whereas if you document the proc macros in the inner crate, hovering on macro calls in the outer crate or in crates that use the outer crate will result in you seeing docs for the proc macro.

TLDR: handle docs that are added by re-exports the same way that cargo doc does -- prepend these docs to the beginning of the docs page for that item.

Note: this might also apply to other items -- I only really care about this as it pertains to proc macros, but it could very well also apply to things like function and trait exports, etc.

[Veykril]

This is blocked on us not handling attributes on re-exports at all (will note some thought about that general topic down later as it becomes more and more apparent that we should fix that)

[sam0x17]

Makes sense. My preference of course would be for rust-analyzer to match the cargo doc behavior, though I do wish cargo doc appended re-export docs instead of prepending them as a typical use-case would be tacking on some "See also" stuff at the end where outer traits are available :/