rust-lang / rust-lang/rust

Unexpected warning when doc string invokes a macro which is defined within the same module

Open
#133,656 5 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

A-macros A-resolve C-bug T-compiler
Dominant language
Rust
Stars
119k
Forks
16.1k
PR merge metrics
PR metrics pending

Description

This is a follow-up of https://github.com/rust-lang/rust/issues/124535#issuecomment-2466005846.

TLDR: it looks like https://github.com/rust-lang/rust/issues/124535 might have not been completely resolved, or at least there are some undetected edge cases in https://github.com/rust-lang/rust/pull/125741/commits/c4c7859e40efcfff640af442fb5d1fab3718d374...

Issue Description

In the minimal reproduction (rami3l/repro_rust_124535), we have:

// lib.rs
macro_rules! pm_mods {
    ( $( $vis:vis $mod:ident; )+ ) => {
        $(
            $vis mod $mod;
            pub use self::$mod::$mod;
        )+
    }
}

pm_mods! {
    dnf;
}
// dnf.rs
#![doc = doc_self!()]

macro_rules! doc_self {
    () => {
        "The Dandified YUM."
    };
}
use doc_self; // <- Please note that the suggested fix has already been applied.

#[doc = doc_self!()]
pub fn dnf() {}

I expected to see this happen: ✅

Instead, this happened:

> cargo check
    Checking repro_rust_124535 v0.1.0 (/path/censored)
warning: cannot find macro `doc_self` in this scope
 --> src/dnf.rs:1:10
  |
1 | #![doc = doc_self!()]
  |          ^^^^^^^^
  |
  = warning: this was previously accepted by the compiler but is being phased out; it will become a hard error in a future release!
  = note: for more information, see issue #124535 <https://github.com/rust-lang/rust/issues/124535>
  = help: import `macro_rules` with `use` to make it callable above its definition
  = note: `#[warn(out_of_scope_macro_calls)]` on by default

warning: `repro_rust_124535` (lib) generated 1 warning
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.06s

Also, it's worth noticing that after inlining the macro invocation in lib.rs, i.e.:

// lib.rs
mod dnf;
pub use self::dnf::dnf;

... the error seems gone.

Meta

rustc --version --verbose:

rustc 1.83.0 (90b35a623 2024-11-26)
binary: rustc
commit-hash: 90b35a6239c3d8bdabc530a6a0816f7ff89a0aaf
commit-date: 2024-11-26
host: aarch64-apple-darwin
release: 1.83.0
LLVM version: 19.1.1

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

Reproduce the warning with the lib.rs and dnf.rs examples from the issue, starting with cargo check on the minimal reproduction. Compare the macro invocation generated by pm_mods! with the explicit mod dnf form. Done means the same-module doc macro is resolved without the out_of_scope_macro_calls warning.

Written by the indexing model from the issue text.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.