rust-lang / rust-lang/rust-analyzer

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

Open
#13,431 4 comments 4 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

A-ide C-bug S-unactionable
Dominant language
Rust
Stars
16.9k
Forks
2.2k
Avg merge
1d 12h
Merged PRs (30d)
72

Description

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.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reproducing the proc-macro setup shown in inner_crate/lib.rs and outer_crate/main.rs, then compare rust-analyzer hover output with cargo doc for the re-export. The work is done when documentation added at the re-export is shown and prepended to the original proc-macro documentation, including when only the re-export has docs.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
compilers, devtools
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.