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.

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