rust-lang / rust-lang/rust

Invalid broken link lint suggestion when referencing disambiguous attribute macro

Open
#159,771 1 comment 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

A-diagnostics A-intra-doc-links A-suggestion-diagnostics C-bug D-invalid-suggestion T-rustdoc
Dominant language
Rust
Stars
119k
Forks
16.1k
PR merge metrics
PR metrics pending

Description

Code

#![feature(macro_attr)]

mod example {}

#[macro_export]
macro_rules! example {
    attr() () => {

    };
}


/// Check out my cool macro [`example`](crate::example!)
fn main() {}

Reproduction Steps

Run cargo doc

Expected Outcome

When there is an ambiguity in a intra-doc link when referencing a macro_rules! defined attribute macro, rustdoc's recommended fix is wrong, If applying the suggested ambiguator, it will complain about an unknown ambiguator.
I either expect attribute@ to be supported, or the suggestion be changed to macro@ which works as expected.

Actual Output

warning: incompatible link kind for `crate::example`
  --> src/main.rs:13:41
   |
13 | /// Check out my cool macro [`example`](crate::example!)
   |                                         ^^^^^^^^^^^^^^^ this link resolved to an attribute macro, which is not a macro
   |
   = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default
help: to link to the attribute macro, prefix with `attribute@`
   |
13 - /// Check out my cool macro [`example`](crate::example!)
13 + /// Check out my cool macro [`example`](attribute@crate::example)
   |

After applying suggested fix

warning: unknown disambiguator `attribute`
  --> src/main.rs:13:41
   |
13 | /// Check out my cool macro [`example`](attribute@crate::example)
   |                                         ^^^^^^^^^
   |
   = note: see https://doc.rust-lang.org/nightly/rustdoc/write-documentation/linking-to-items-by-name.html#namespaces-and-disambiguators for more info about disambiguators
   = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default

Version

rustdoc 1.99.0-nightly (6f72b5dd5 2026-07-22)

Additional Details

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 warning with the provided Rust snippet and cargo doc, then trace rustdoc's intra-doc link disambiguator handling for attribute macros. The fix is complete when the diagnostic suggests a supported disambiguator, such as macro@, or the suggested attribute@ form is accepted without a second warning.

Written by the indexing model from the issue text.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.