cfg_attrs 2.1.1

An alternative to #[cfg_attr(...)] that is easier to use with doc comments.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105

<!-- This Source Code Form is subject to the terms of the Mozilla Public
   - License, v. 2.0. If a copy of the MPL was not distributed with this
   - file, You can obtain one at https://mozilla.org/MPL/2.0/. -->

Provides an alternative syntax to [`#[cfg_attr(...)]`][cfg_attr] that is easier to use with doc
comments.

> <sup>Syntax</sup> \
> _CfgAttrsAttribute_ : \
> &nbsp;&nbsp;`cfg_attrs` `{` _Attribute_<sup>\*</sup> `}`
>
> _Attribute_ : \
> &nbsp;&nbsp;_ConfigureAttribute_ | [_OuterAttribute_]
>
> _ConfigureAttribute_ : \
> &nbsp;&nbsp; `#` `[` `configure` `(` _ConfigureMeta_ `)` `]`
>
> _ConfigureMeta_ : \
> &nbsp;&nbsp; [_ConfigurationPredicate_] `,` _Attributes_
>
> _Attributes_ : \
> &nbsp;&nbsp;_Attribute_<sup>\*</sup> ( `,` _Attribute_<sup>\*</sup> )<sup>\*</sup> `,`<sup>?</sup>

[_ConfigurationPredicate_]: https://doc.rust-lang.org/reference/conditional-compilation.html
[_OuterAttribute_]: https://doc.rust-lang.org/reference/attributes.html

# Usage
`#[cfg_attrs { ... }]` should surround all other attributes on the item. A
`#[configure(<condition>, <attributes>)]` helper attribute is provided within.

The syntax of that `#[configure(...)]` attribute is much like [`#[cfg_attr(...)]`][cfg_attr], except
the configured attributes use full attribute syntax. The advantage of this is that doc comments,
which expand to `#[doc = "..."]` attributes, can be used in the `#[configure(...)]` syntax.

<div class="warning">

All of an item's doc comments should be placed within the `#[cfg_attrs { ... }]` attribute, even
if they are not being configured. Additionally, the `#[cfg_attrs { ... }]` attribute should only
appear once per item; `#[configure(...)]` can be used multiple times within it if you want
multiple usages.

</div>

These restrictions are as a result of how proc-macro attributes work: they are expanded
separately to other attributes, so their position among other attributes is lost. While you
might put a `#[cfg_attrs { ... }]` attribute that configures doc comments between two
non-configured doc comments, that isn't where it will be expanded to, so the documentation will
be out of order.

# Examples
```
# use cfg_attrs::cfg_attrs;
#
#[cfg_attrs {
    /// This is an example struct.
    #[configure(
        debug_assertions,
        ///
        /// Hello! These are docs that only appear when
        /// debug assertions are active.
    )]
}]
struct Example;
```
This will expand to the following usage of [`#[cfg_attr(...)]`][cfg_attr]:
```rust
/// This is an example struct.
#[cfg_attr(
    debug_assertions,
    doc = "",
    doc = " Hello! These are docs that only appear when",
    doc = " debug assertions are active."
)]
struct Example;
```
Which, if debug assertions are active, would be expanded to:
```rust
/// This is an example struct.
///
/// Hello! These are docs that only appear when
/// debug assertions are active.
struct Example;
```

`#[cfg_attrs(...)]` may also be used with attributes other than doc comments, though there is
no real benefit to doing this:
```
# use cfg_attrs::cfg_attrs;
#
#[cfg_attrs {
    #[configure(
        feature = "magic",
        #[sparkles]
        #[crackles]
    )]
}]
fn bewitched() {}
```
With that example expanding to:
```rust
#[cfg_attr(feature = "magic", sparkles, crackles)]
fn bewitched() {}
```

[cfg_attr]: https://doc.rust-lang.org/reference/conditional-compilation.html#the-cfg_attr-attribute