Crate is not clear enough about cfg-if being limited to items

[Bryant Mairs]

I was trying to generate a bunch of identical functions with different bodies, so I was writing them similar to this minimal example:

#[macro_use]
extern crate cfg_if;

fn a() {}
            
fn b() {
    cfg_if! {
        if #[cfg(target_os = "linux")] {
            a()
        }
    }
}

fn main() {
    b();
}

but this fails with:

error: expected one of `!` or `::`, found `(`
 --> src/main.rs:9:14
  |
9 |             a()
  |              ^ expected one of `!` or `::` here

error: Could not compile `playground`.

To learn more, run the command again with --verbose.

This was very confusing and I didn't see anything about this in the generated cfg-if docs. I went on the Rust IRC channel and scottmcm was kind enough to point out that in the crate description visible on Crates.io "A macro to ergonomically define an item depending on a large number of #[cfg] parameters. Structured like an if-else chain, the first matching branch is the item that gets emitted." it talks about items, which are a specific language term.

So now I understand a little bit better the limitations, I think there are two ways to better convey this to users:

• Use the term item within the generated docs and be sure to link to the relevant section in the reference that I linked to above.
• Emit better errors for when there isn't a macro match (not certain if this is currently possible).

[Alex Crichton]

Yeah I definitely think the documentation could be improved!

[Alex Crichton]

As of #28 expressions and arbitrary tokens are now allowed