libcore documentation for builtin macros

src/libcore/macros.rs

@@ -509,3 +509,143 @@ macro_rules! unreachable {
 macro_rules! unimplemented {
     () => (panic!("not yet implemented"))
 }
+
+/// Built-in macros to the compiler itself.
+///
+/// These macros do not have any corresponding definition with a `macro_rules!`
+/// macro, but are documented here. Their implementations can be found hardcoded
+/// into libsyntax itself.
+///
+/// For more information, see documentation for `std`'s macros.
+#[cfg(dox)]
+pub mod builtin {
+    /// The core macro for formatted string creation & output.
+    ///
+    /// For more information, see the documentation for [`std::format_args!`].
+    ///
+    /// [`std::format_args!`]: ../std/macro.format_args.html
+    #[stable(feature = "rust1", since = "1.0.0")]
+    #[macro_export]
+    macro_rules! format_args { ($fmt:expr, $($args:tt)*) => ({
+        /* compiler built-in */
+    }) }
+
+    /// Inspect an environment variable at compile time.
+    ///
+    /// For more information, see the documentation for [`std::env!`].
+    ///
+    /// [`std::env!`]: ../std/macro.env.html
+    #[stable(feature = "rust1", since = "1.0.0")]
+    #[macro_export]
+    macro_rules! env { ($name:expr) => ({ /* compiler built-in */ }) }
+
+    /// Optionally inspect an environment variable at compile time.
+    ///
+    /// For more information, see the documentation for [`std::option_env!`].
+    ///
+    /// [`std::option_env!`]: ../std/macro.option_env.html
+    #[stable(feature = "rust1", since = "1.0.0")]
+    #[macro_export]
+    macro_rules! option_env { ($name:expr) => ({ /* compiler built-in */ }) }
+
+    /// Concatenate identifiers into one identifier.
+    ///
+    /// For more information, see the documentation for [`std::concat_idents!`].
+    ///
+    /// [`std::concat_idents!`]: ../std/macro.concat_idents.html
+    #[unstable(feature = "concat_idents", issue = "29599")]
+    #[macro_export]
+    macro_rules! concat_idents {
+        ($($e:ident),*) => ({ /* compiler built-in */ })
+    }
+
+    /// Concatenates literals into a static string slice.
+    ///
+    /// For more information, see the documentation for [`std::concat!`].
+    ///
+    /// [`std::concat!`]: ../std/macro.concat.html
+    #[stable(feature = "rust1", since = "1.0.0")]
+    #[macro_export]
+    macro_rules! concat { ($($e:expr),*) => ({ /* compiler built-in */ }) }
+
+    /// A macro which expands to the line number on which it was invoked.
+    ///
+    /// For more information, see the documentation for [`std::line!`].
+    ///
+    /// [`std::line!`]: ../std/macro.line.html
+    #[stable(feature = "rust1", since = "1.0.0")]
+    #[macro_export]
+    macro_rules! line { () => ({ /* compiler built-in */ }) }
+
+    /// A macro which expands to the column number on which it was invoked.
+    ///
+    /// For more information, see the documentation for [`std::column!`].
+    ///
+    /// [`std::column!`]: ../std/macro.column.html
+    #[stable(feature = "rust1", since = "1.0.0")]
+    #[macro_export]
+    macro_rules! column { () => ({ /* compiler built-in */ }) }
+
+    /// A macro which expands to the file name from which it was invoked.
+    ///
+    /// For more information, see the documentation for [`std::file!`].
+    ///
+    /// [`std::file!`]: ../std/macro.file.html
+    #[stable(feature = "rust1", since = "1.0.0")]
+    #[macro_export]
+    macro_rules! file { () => ({ /* compiler built-in */ }) }
+
+    /// A macro which stringifies its argument.
+    ///
+    /// For more information, see the documentation for [`std::stringify!`].
+    ///
+    /// [`std::stringify!`]: ../std/macro.stringify.html
+    #[stable(feature = "rust1", since = "1.0.0")]
+    #[macro_export]
+    macro_rules! stringify { ($t:tt) => ({ /* compiler built-in */ }) }
+
+    /// Includes a utf8-encoded file as a string.
+    ///
+    /// For more information, see the documentation for [`std::include_str!`].
+    ///
+    /// [`std::include_str!`]: ../std/macro.include_str.html
+    #[stable(feature = "rust1", since = "1.0.0")]
+    #[macro_export]
+    macro_rules! include_str { ($file:expr) => ({ /* compiler built-in */ }) }
+
+    /// Includes a file as a reference to a byte array.
+    ///
+    /// For more information, see the documentation for [`std::include_bytes!`].
+    ///
+    /// [`std::include_bytes!`]: ../std/macro.include_bytes.html
+    #[stable(feature = "rust1", since = "1.0.0")]
+    #[macro_export]
+    macro_rules! include_bytes { ($file:expr) => ({ /* compiler built-in */ }) }
+
+    /// Expands to a string that represents the current module path.
+    ///
+    /// For more information, see the documentation for [`std::module_path!`].
+    ///
+    /// [`std::module_path!`]: ../std/macro.module_path.html
+    #[stable(feature = "rust1", since = "1.0.0")]
+    #[macro_export]
+    macro_rules! module_path { () => ({ /* compiler built-in */ }) }
+
+    /// Boolean evaluation of configuration flags.
+    ///
+    /// For more information, see the documentation for [`std::cfg!`].
+    ///
+    /// [`std::cfg!`]: ../std/macro.cfg.html
+    #[stable(feature = "rust1", since = "1.0.0")]
+    #[macro_export]
+    macro_rules! cfg { ($($cfg:tt)*) => ({ /* compiler built-in */ }) }
+
+    /// Parse a file as an expression or an item according to the context.
+    ///
+    /// For more information, see the documentation for [`std::include!`].
+    ///
+    /// [`std::include!`]: ../std/macro.include.html
+    #[stable(feature = "rust1", since = "1.0.0")]
+    #[macro_export]
+    macro_rules! include { ($file:expr) => ({ /* compiler built-in */ }) }
+}

src/libstd/macros.rs

@@ -381,9 +381,11 @@ pub mod builtin {
 
     /// Includes a utf8-encoded file as a string.
     ///
+    /// The file is located relative to the current file. (similarly to how
+    /// modules are found)
+    ///
     /// This macro will yield an expression of type `&'static str` which is the
-    /// contents of the filename specified. The file is located relative to the
-    /// current file (similarly to how modules are found),
+    /// contents of the file.
     ///
     /// # Examples
     ///
@@ -396,9 +398,11 @@ pub mod builtin {
 
     /// Includes a file as a reference to a byte array.
     ///
+    /// The file is located relative to the current file. (similarly to how
+    /// modules are found)
+    ///
     /// This macro will yield an expression of type `&'static [u8; N]` which is
-    /// the contents of the filename specified. The file is located relative to
-    /// the current file (similarly to how modules are found),
+    /// the contents of the file.
     ///
     /// # Examples
     ///
@@ -452,9 +456,10 @@ pub mod builtin {
     #[macro_export]
     macro_rules! cfg { ($($cfg:tt)*) => ({ /* compiler built-in */ }) }
 
-    /// Parse the file provided in the argument as an expression or an
-    /// item according to the context. This file is located relative
-    /// to the current file (similarly to how modules are found).
+    /// Parse a file as an expression or an item according to the context.
+    ///
+    /// The file is located relative to the current file. (similarly to how
+    /// modules are found)
     ///
     /// Using this macro is often a bad idea, because if the file is
     /// parsed as an expression, it is going to be placed in the