Auto merge of #37325 - newpavlov:master, r=frewsxcv

libcore documentation for builtin macros

Fixes: #36272

Additionally I've edited docstring for `include!` a bit. (related PR #36404)

Unfortunately it seems there is no sane way to reexport empty macros definitions for their docstrings. To avoid copying the whole documentation for builtin macros I've only copied description and added links to `std` macro pages.

1 files changed, 140 insertions, 0 deletions

diff --git a/src/libcore/macros.rs b/src/libcore/macros.rs
index 6e08abd3461..5142b18dca1 100644
--- a/src/libcore/macros.rs
+++ b/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 */ }) }
+}