From ce8e4e71f8013a98eadec7c89e1782bd78c016c9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=90=D1=80=D1=82=D1=91=D0=BC=20=D0=9F=D0=B0=D0=B2=D0=BB?= =?UTF-8?q?=D0=BE=D0=B2=20=5BArtyom=20Pavlov=5D?= Date: Fri, 21 Oct 2016 17:23:50 +0300 Subject: [PATCH 1/3] libcore documentation for builtin macros --- src/libcore/macros.rs | 142 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 142 insertions(+) diff --git a/src/libcore/macros.rs b/src/libcore/macros.rs index 6e08abd346143..bf58fddbfbd82 100644 --- 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 */ }) } +} From b374c53ae6af8c64340ef98c69335d21ce2f8334 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=90=D1=80=D1=82=D1=91=D0=BC=20=D0=9F=D0=B0=D0=B2=D0=BB?= =?UTF-8?q?=D0=BE=D0=B2=20=5BArtyom=20Pavlov=5D?= Date: Fri, 21 Oct 2016 17:44:19 +0300 Subject: [PATCH 2/3] Small doc change for include! --- src/libcore/macros.rs | 4 +--- src/libstd/macros.rs | 7 ++++--- 2 files changed, 5 insertions(+), 6 deletions(-) diff --git a/src/libcore/macros.rs b/src/libcore/macros.rs index bf58fddbfbd82..5142b18dca113 100644 --- a/src/libcore/macros.rs +++ b/src/libcore/macros.rs @@ -640,9 +640,7 @@ 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. /// /// For more information, see the documentation for [`std::include!`]. /// diff --git a/src/libstd/macros.rs b/src/libstd/macros.rs index 40e5dd6ba1903..006853063f53c 100644 --- a/src/libstd/macros.rs +++ b/src/libstd/macros.rs @@ -452,9 +452,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 From 34576da9355b5de993e3d08a317f00240f53c5b1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=90=D1=80=D1=82=D1=91=D0=BC=20=D0=9F=D0=B0=D0=B2=D0=BB?= =?UTF-8?q?=D0=BE=D0=B2=20=5BArtyom=20Pavlov=5D?= Date: Fri, 21 Oct 2016 18:03:22 +0300 Subject: [PATCH 3/3] Small docstring changes for include_bytes and include_str --- src/libstd/macros.rs | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/src/libstd/macros.rs b/src/libstd/macros.rs index 006853063f53c..d801fa028cc0d 100644 --- a/src/libstd/macros.rs +++ b/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 /// @@ -454,7 +458,7 @@ pub mod builtin { /// 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 + /// 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