reference: clarify #[cfg] section

[durka]

Closes #39370, but maybe we (or clippy) should add a warning too.

[rust-highfive]

r? @steveklabnik

(rust_highfive has picked a reviewer for you, use r? to override)

[bluss]

It's still misleading, there is no "contains a string". Variables feature="a" and feature="b" can be independently set, so there is no feature and it doesn't contain either a or b.

[durka]

At least it does collapse whitespace though, so --cfg 'x="y"' and --cfg 'x = "y"' mean the same thing. So it does give the appearance of a property named x that contains the value "y". However, x can take on multiple values at the same time.

[durka]

@bluss updated, what do you think?

[bluss]

better but why should we say there are two kinds of configuration options, when there is just one? first and second="x" are both just names of cfg vars that can be on or off. Also some old text left in here at the end.

[durka]

I think this might be a "compiler-colored glasses" kind of thing: it certainly _feels_ like they are separate types of cfgs to the user.

…

On Mon, Jan 30, 2017 at 4:49 PM, bluss ***@***.***> wrote: ***@***.**** commented on this pull request. ------------------------------ In src/doc/reference.md <#39374 (review)>: > -(`#[cfg(foo)]`), and the other that contains a string that can be checked -against (`#[cfg(bar = "baz")]`). Currently, only compiler-defined configuration -options can have the latter form. +There are two kinds of configuration options: + +- Boolean options, which are either on or off, e.g. `#[cfg(foo)]`. These can + either be defined by the compiler or specified on the command line, e.g. + `rustc --cfg foo`. +- Key-value options, where a key may be associated with one or more values, e.g. + `#[cfg(bar = "baz")]`. These can also either be defined by the compiler or + specified on the command line, e.g. `rustc --cfg 'bar="baz"'` (whitespace around + the `=` is ignored). + +one that is either defined or not +(`#[cfg(foo)]`), and the other that takes on one or more string values +(`#[cfg(bar = "baz")]`). better but why should we say there are two kinds of configuration options, when there is just one? first and second="x" are both just names of cfg vars. Also some old text left in here at the end. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#39374 (review)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAC3nyrAtAdsVFWTMKRjrFvDpgeIHbJEks5rXlr-gaJpZM4LwoR4> .

[codyps]

As someone who just recently realized that "first and second="x" are both just names of cfg vars", my opinion is that knowing that is the actual meaning makes them much easier to think about.

Talking about associated keys seems to just confuse things.

[durka]

OK, new draft:

Configuration options are boolean (on or off) and are named either with a single identifier (e.g. foo) or an identifier and a string (e.g. foo = "bar"; the quotes are required and spaces around the = are unimportant). Note that similarly-named options, such as foo, foo="bar" and foo="baz" may each be set or unset independently.

Configuration options are either provided by the compiler or passed in on the command line using --cfg (e.g. rustc main.rs --cfg foo --cfg 'bar="baz"').

[steveklabnik]

durka: r=me with that change.

[durka]

OK, done. I also added a mention of cfg!. Will squash (wish you could do that with the web editor...).

[bluss]

@bors r=steveklabnik

Great!

[bors]

📌 Commit 620074d has been approved by steveklabnik