README.md

#[cfg_attrs { ... }]

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

^Syntax
CfgAttrsAttribute :
  cfg_attrs

Attribute :
  ConfigureAttribute | OuterAttribute

ConfigureAttribute :
   # [ configure ( ConfigureMeta ) ]

ConfigureMeta :
   ConfigurationPredicate , Attributes

Attributes :
  Attribute^* ( , Attribute^* )^* ,^?

Usage

Placing #[cfg_attrs] on an item enables a #[configure(<condition>, <attributes>)] helper attribute to be used on that item.

The syntax of that #[configure(...)] attribute is much like #[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.

Examples

#[cfg_attrs]
/// This is an example struct.
#[configure(
    debug_assertions,
    ///
    /// Hello! These are docs that only appear when
    /// debug assertions are active.
)]
enum Example {
    #[configure(
        feature = "magic",
        /// Woah! Look at that! It enables
        /// `#[configure(...)]` for variants too!
    )]
    Point {
        #[configure(
            feature = "magic",
            /// And fields! This is amazing!
        )]
        x: i32,
        y: i32,
    },
}

This will expand to the following usage of #[cfg_attr(...)]:

/// This is an example enum.
#[cfg_attr(
    debug_assertions,
    doc = "",
    doc = " Hello! These are docs that only appear when",
    doc = " debug assertions are active."
)]
enum Example {
    #[cfg_attr(
        feature = "magic",
        doc = " Woah! Look at that! It enables",
        doc = " `#[configure(...)]` for variants too!"
    )]
    Point {
        #[cfg_attr(
            feature = "magic",
            doc = " And fields! This is amazing!"
        )]
        x: i32,
        y: i32,
    },
}

Which, if debug assertions are active, would be expanded to:

/// This is an example enum.
///
/// Hello! These are docs that only appear when
/// debug assertions are active.
enum Example {
    Point {
        x: i32,
        y: i32,
    },
}

Or, if the magic feature is enabled:

/// This is an example enum.
enum Example {
    /// Woah! Look at that! It enables
    /// `#[configure(...)]` for variants too!
    Point {
        /// And fields! This is amazing!
        x: i32,
        y: i32,
    },
}

#[cfg_attrs(...)] may also be used with attributes other than doc comments, though there is no real benefit to doing this:

#[cfg_attrs]
#[configure(
    feature = "magic",
    #[sparkles]
    #[crackles]
)]
fn bewitched() {}

With that example expanding to:

#[cfg_attr(feature = "magic", sparkles, crackles)]
fn bewitched() {}

And expanding, if the magic feature is enabled, to:

#[sparkles]
#[crackles]
fn bewitched() {}