/// This macro takes any number of comma-separated identifiers, and
/// concatenates them all into one, yielding an expression which is a new
/// identifier. Note that hygiene makes it such that this macro cannot
- /// capture local variables, and macros are only allowed in item,
- /// statement or expression position, meaning this macro may be difficult to
- /// use in some situations.
+ /// capture local variables. Also, as a general rule, macros are only
+ /// allowed in item, statement or expression position. That means while
+ /// you may use this macro for referring to existing variables, functions or
+ /// modules etc, you cannot define a new one with it.
///
/// # Examples
///
///
/// let f = concat_idents!(foo, bar);
/// println!("{}", f());
+ ///
+ /// // fn concat_idents!(new, fun, name) { } // not usable in this way!
/// # }
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
/// stringification of all the tokens passed to the macro. No restrictions
/// are placed on the syntax of the macro invocation itself.
///
+ /// Note that the expanded results of the input tokens may change in the
+ /// future. You should be careful if you rely on the output.
+ ///
/// # Examples
///
/// ```