`ensure!` macro implementation details about anyhow

[conradludgate]

The __parse_ensure macro is used to allow the following error messages:

let (x, y) = (5, 6);
anyhow::ensure!(x == y);

into

Error: Condition failed: `x == y` (5 vs 6)

An example output of the macro

match (&x, &y) {
    (lhs, rhs) => {
        if !(lhs == rhs) {
            #[allow(unused_imports)]
            use ::anyhow::__private::{BothDebug, NotBothDebug};
            return Err((lhs, rhs).__dispatch_ensure("Condition failed: `x == y`"));
        }
    }
}

It is complicated but necessary for these nicer error messages.

[gimbling-away]

Sure, this is valid. But the documentation is still misleading. (Especially since clicking source leads to the wrong definition) and could the implementation of this not have been simpler?

[Nilstrieb]

It's not really misleading, it's documentation on how to use the macro. The actual implementation would generate very useless documentation that would not serve the job of documentation - describing how the macro can be used.

[gimbling-away]

Sure, that can be in the docs itself though, rather than pointing to a completely different macro entirely.

The compile time influence of this is still unconsidered. See: std having different assert macros for special-cased error messages, rather than overloading a single macro.

[gimbling-away]

The current solution is not very accurate either, look at the expansion of this:

use anyhow::ensure;

ensure!(true == true || false == true);

use anyhow::ensure;

if !(true == true || false == true) {
    return ::anyhow::__private::Err(::anyhow::Error::msg(
        "Condition failed: `true == true || false == true`",
    ));
};

It doesn't detect the == operation occurring and add the specialized diagnostic.
The condition is parsed by syn as true == (true || (false == true))

A proc macro for this should be much better, imo. It would both more accurately perform this and should hopefully be faster than the decl macro implementation right now. 🤷🏽‍♀️

[dtolnay]

#325 (comment) is accurate about why it's set up this way. The input patterns shown are indeed the 4 patterns that the macro accepts. The real macro implementation just parses the same things token-by-token instead of through macro_rules's built-in $:expr parser.

[gimbling-away]

Sure. But the "source" of the macro according to the docs is still completely misleading.
When I click "source" on the docs, there's no comment or no indication at all (neither in the docs themselves nor in any comment in the source code) to the actual implementation of the macro. It just points to a pseudo-macro.
If I hadn't noticed the tiny cfgs, I would've been completely oblivious to this too.

This is still ignoring

• The compile time affect of this
• The accuracy of this (#325 (comment))

Hacking together a semi-parser of Rust code in a declarative macro seems unnecessary and a misuse of them. A proc-macro seems much better suited here?

[gimbling-away]

If the point of the cfg(docs) macro is to simply be a place holder for the docs, why implement at all?

Especially since the implementation of the only-docs macro is not the expansion of the actual macro