libcore documentation for builtin macros

diff --git a/src/libcore/macros.rs b/src/libcore/macros.rs
index 6e08abd34614386c41479764b91248ea788f23d0..bf58fddbfbd828893919419eaa080444d79999e3 100644 (file)
--- a/src/libcore/macros.rs
+++ b/src/libcore/macros.rs
@@ -509,3 +509,145 @@ 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 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).
+    ///
+    /// 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 */ }) }
+}