X-Git-Url: https://git.lizzy.rs/?a=blobdiff_plain;f=src%2Flibstd%2Fmacros.rs;h=d241cd032ed4c07872f56a632077a59fabd93d4a;hb=a70ae2ffb9a5dd08d916b9938eeca820486ba7a0;hp=0917346213f4aa936eb9cdb5870639426422942d;hpb=56a1f51ef0b26acb0d6eb2a7dbe9336f5e942061;p=rust.git

diff --git a/src/libstd/macros.rs b/src/libstd/macros.rs
index 0917346213f..d241cd032ed 100644
--- a/src/libstd/macros.rs
+++ b/src/libstd/macros.rs
@@ -269,9 +269,10 @@ macro_rules! option_env { ($name:expr) => ({ /* compiler built-in */ }) }
     /// 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
     ///
@@ -283,6 +284,8 @@ macro_rules! option_env { ($name:expr) => ({ /* compiler built-in */ }) }
     ///
     /// 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")]
@@ -365,6 +368,9 @@ macro_rules! file { () => ({ /* compiler built-in */ }) }
     /// 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
     ///
     /// ```