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

[danielhenrymantilla]

Code

I tried this code:

mod module {
    #![doc = foo!()]

    macro_rules! foo {() => (
        ""
    )}
}

I expected to see this happen:

✅

Instead, this happened:

error: cannot find macro `foo` in this scope
 --> src/lib.rs:2:14
  |
2 |     #![doc = foo!()]
  |              ^^^ consider moving the definition of `foo` before this call
  |
note: a macro with the same name exists, but it appears later at here
 --> src/lib.rs:4:18
  |
4 |     macro_rules! foo {
  |                  ^^^

Remark

Note that this problem still does not occur at the top-most level.

That is, removing mod module { above makes it work:

#![doc = foo!()]

macro_rules! foo {() => (
    ""
)}

Version it worked on

It most recently worked on: +nightly-2024-04-27

Version with regression

rustc --version --verbose:

+nightly-2024-04-28

---

@rustbot modify labels: +regression-from-stable-to-nightly -regression-untriaged

[bjorn3]

Why did it work at all? The doc comment is defined earlier in the source order than the macro, so it shouldn't be able to see the macro.

[lqd]

This is from #124382 cc @petrochenkov

[petrochenkov]

The AST visiting order (mutable and immutable) was tweaked in #124382, yes.
Not sure which exactly pass is responsible for the change though.

The new behavior looks correct to me, foo is not in scope at the doc comment's location.
I wonder how widespread this breakage is.

[danielhenrymantilla]

I agree it could be sensible not to try to keep backcompat too much, and "tank" the breakage. Especially since adding a use foo; after the macro definition (as it is already customarily done so that a macro become nameable before its definition) does make the error go away:

  mod module {
    #![doc = foo!()]

    macro_rules! foo {() => (
        ""
    )}
+   use foo;
  }

I am fine doing this for my safer-ffi crate which runs into this; I was just worried about doc strings potentially ending up, eventually, fully unable to refer to macros defined within the module.

---

I do think something ought to be done w.r.t. the root/top-level lib.rs module, since that one has not regressed, meaning it is currently still possible to have:

#![doc = foo!()]

macro_rules! foo {() => (
    ""
)}

working, which given the current issue, hints at some future regression eventually happening in the future: it could thus warrant a FCW, or a fully-fledged breakage here and now?

[petrochenkov]

Note, that name resolution for inner attributes is not well defined, and that's why non-builtin inner attributes are unstable.

#![my::attribute] // ERROR: custom inner attributes are unstable

For the same reasons it would be reasonable to keep #![key = value!()] unstable as well, but apparently nobody thought about this in time.

The situation with #![key = value!()] is better than with inner attributes in general though, because at least it cannot transform content of the module it's applied to into something different.
So in mod foo { #![key = value!()] /*items*/ } we can resolve value inside mod foo without it going from under our feet.

[petrochenkov]

I think my preference would be fixing the root module case, auditing the implementation for other possible interesting cases, and then running crater to see what code is affected.

[rami3l]

I've encountered this very issue (with rustdoc, but I guess it's the same thing), but the error messages seem a bit different, so it took me quite a while to find this issue here... I'll paste my minimal repro here so that it might help someone after me:

src/lib.rs

mod foo {
  #![doc = foo!()]
  macro_rules! foo { () => { "foo" } }
  #[doc = foo!()] struct Foo;
}

Before

> cargo doc --all-features --document-private-items --no-deps
 Documenting foo v0.1.0 (/Users/rami3l/Downloads/foo)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.18s
   Generated /Users/rami3l/Downloads/foo/target/doc/foo/index.html

> rustdoc --version
rustdoc 1.78.0 (9b00956e5 2024-04-29)

After

> cargo +beta doc --all-features --document-private-items --no-deps
 Documenting foo v0.1.0 (/Users/rami3l/Downloads/foo)
error: cannot find macro `foo` in this scope
 --> src/lib.rs:2:12
  |
2 |   #![doc = foo!()]
  |            ^^^
  |
  = help: have you added the `#[macro_use]` on the module/import?

error: could not document `foo`

> rustdoc +beta --version
rustdoc 1.79.0-beta.2 (4bf9354b9 2024-05-02)

Conclusion

If the use foo; approach is recommended, then the help message could use some improvements here.

[petrochenkov]

Fixed in #125734.

[lqd]

Reopening to track beta backport

[Mark-Simulacrum]

Closing, backported in #126093.