Document local_inner_macros

[SimonSapin]

Was: `matches` crate regression: error[E0433]: failed to resolve. Did you mean `std::panic`?

---

Reduced test case:

#[macro_export(local_inner_macros)]
macro_rules! assert_matches {
    () => {
        panic!()
    }
}

fn main() {
    assert_matches!();
}

$ rustup run --install nightly-2018-08-17 rustc -V  
rustc 1.30.0-nightly (b2028828d 2018-08-16)
$ rustup run --install nightly-2018-08-17 rustc a.rs
$ rustup run --install nightly-2018-08-18 rustc -V 
rustc 1.30.0-nightly (1fa944914 2018-08-17)
$ rustup run --install nightly-2018-08-18 rustc a.rs
error[E0433]: failed to resolve. Did you mean `std::panic`?
 --> a.rs:4:9
  |
4 |         panic!()
  |         ^^^^^ Did you mean `std::panic`?
...
9 |     assert_matches!();
  |     ------------------ in this macro invocation

error: aborting due to previous error

For more information about this error, try `rustc --explain E0433`.

Commit range: b202882...1fa9449
Likely candidate: #50911 Stabilize use_extern_macros, CC @petrochenkov

[petrochenkov]

This is local_inner_macros working as specified.

panic!() inside a local_inner_macros macro is transformed into $crate::panic and there's no panic in the current crate root.
See e.g. rust-lang/log#288 for the correct way to use local_inner_macros.

[petrochenkov]

Perhaps diagnostics could be better though, at least mentioning $crate::panic.

[SimonSapin]

Where is this specified? I couldn’t find local_inner_macros in the reference or other docs.

Regardless, this is a case of code that compiles on earlier versions and doesn’t anymore. And it’s probably not the only instance.

[petrochenkov]

@SimonSapin

Where is this specified?

At least in the pull request introducing the feature :)
Ok, this is a doc issue too now.

[petrochenkov]

Oh, I've just noticed, local_inner_macros isn't on stable yet, it's on beta.
Yes, it's not gated and the syntax was accepted on stable since pre-1.0 and ignored - this is exactly the reason why this syntax was chosen since this is a compatibility feature, but the new behavior was implemented recently and it's assumed that library authors don't add local_inner_macros in the ways that break user code.

[dtolnay]

As @petrochenkov explained, the behavior of local_inner_macros is intentional and designed to be ignored by old compilers. Writing this attribute on a macro containing calls to non-local macros is incorrect even if the attribute is ignored by old compilers.

Let's track documentation here and file separate issues if there are concrete suggestions for improvements to the diagnostic.