Improve assert_matches! documentation

[Voultapher]

This new documentation tries to limit the impact of the conceptual pitfall, that the if guard relaxes the constraint, when really it tightens it. This is achieved by changing the text and examples. The previous documentation also chose a rather weird and non-representative example for the if guard, that made it needlessly complicated to understand.

[rustbot]

r? @cuviper

rustbot has assigned @cuviper.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

[Voultapher]

Not sure I understand the CI error:

macro_rules named matches exists in this crate, but it is not in scope at this link's location

It's the same module, and previously

[\`assert!`]

worked, which is also in the same module. Is this a feature thing?

[jieyouxu]

Not sure I understand the CI error:

macro_rules named matches exists in this crate, but it is not in scope at this link's location

It's the same module, and previously

[\`assert!`]

worked, which is also in the same module. Is this a feature thing?

Is it because of declarative macro definition rules? As in, declarative macro matches is defined after you reference it in assert_matches's docs (although that would be a surprising behavior in terms of docs...). Does it work if you write something like [`matches`](crate::matches)

[Voultapher]

Indeed that's it. Didn't know the declaration order also matters for the doc comments. Here is small reproducer:

macro_rules! start {
    () => {};
}

/// [`start!`]
/// [`end!`]
macro_rules! mid {
    () => {};
}

macro_rules! end {
    () => {};
}

fn main() {}

$ cargo doc
[...]
note: `macro_rules` named `end` exists in this crate, but it is not in scope at this link's location

Kind of sad, because it means there is no general way to cross link macros :/ I tried [matches](crate::matches) but that also doesn't work.

[jieyouxu]

Kind of sad, because it means there is no general way to cross link macros :/ I tried matches but that also doesn't work.

Maybe submit an enhancement request issue for this to the rustdoc team, because I feel like it probably should work? Although I can see not wanting to change the behavior to stay consistent with how name resolution works in rustc as well.

[cuviper]

Here is small reproducer:

FWIW, that does work if you add #[macro_export] on end!.

[Voultapher]

FWIW, that does work if you add #[macro_export] on end!.

The stdlib matches macro is already marked #[macro_export], so unfortunately it doesn't work there. Maybe something to do with the new macro syntax for the other macros?

[kadiwa4]

#[macro_export] adds the macro to the crate root as an item, but the doc comment you edited is in macros and not the crate root. IIUC, that's why you have to use a qualified path in your PR but not in the small reproducer.

Another way to make a macro an item (but not in the crate root) is this:

macro_rules! end {
    () => {};
}
use end;

I'm not suggesting that for your PR; but that's what people should do in other crates where they want to have a macro be an item in the local module.

[cuviper]

Looks good -- I just have some comma suggestions.

[cuviper]

You missed the commas that I removed, which do not belong before the preposition. Also, now that I look again, the phrase "meet expectations" should be plural, or else we could more directly say "did not match the pattern."

[Voultapher]

Good catch. Should be fixed now.

[cuviper]

@bors r+ rollup

[cuviper]

Was the bot asleep?

@bors r+ rollup

[cuviper]

@bors r+

[bors]

📌 Commit c45f0a9 has been approved by cuviper

It is now in the queue for this repository.