diff options
Diffstat (limited to 'library/core/src/macros/mod.rs')
| -rw-r--r-- | library/core/src/macros/mod.rs | 46 |
1 files changed, 31 insertions, 15 deletions
diff --git a/library/core/src/macros/mod.rs b/library/core/src/macros/mod.rs index f29cd357d..3b026bc0e 100644 --- a/library/core/src/macros/mod.rs +++ b/library/core/src/macros/mod.rs @@ -1315,22 +1315,41 @@ pub(crate) mod builtin { /// Parses 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). The provided path is interpreted in a platform-specific - /// way at compile time. So, for instance, an invocation with a Windows path - /// containing backslashes `\` would not compile correctly on Unix. + /// **Warning**: For multi-file Rust projects, the `include!` macro is probably not what you + /// are looking for. Usually, multi-file Rust projects use + /// [modules](https://doc.rust-lang.org/reference/items/modules.html). Multi-file projects and + /// modules are explained in the Rust-by-Example book + /// [here](https://doc.rust-lang.org/rust-by-example/mod/split.html) and the module system is + /// explained in the Rust Book + /// [here](https://doc.rust-lang.org/book/ch07-02-defining-modules-to-control-scope-and-privacy.html). + /// + /// The included file is placed in the surrounding code + /// [unhygienically](https://doc.rust-lang.org/reference/macros-by-example.html#hygiene). If + /// the included file is parsed as an expression and variables or functions share names across + /// both files, it could result in variables or functions being different from what the + /// included file expected. + /// + /// The included file is located relative to the current file (similarly to how modules are + /// found). The provided path is interpreted in a platform-specific way at compile time. So, + /// for instance, an invocation with a Windows path containing backslashes `\` would not + /// compile correctly on Unix. /// - /// 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 - /// surrounding code unhygienically. This could result in variables - /// or functions being different from what the file expected if - /// there are variables or functions that have the same name in - /// the current file. + /// # Uses + /// + /// The `include!` macro is primarily used for two purposes. It is used to include + /// documentation that is written in a separate file and it is used to include [build artifacts + /// usually as a result from the `build.rs` + /// script](https://doc.rust-lang.org/cargo/reference/build-scripts.html#outputs-of-the-build-script). + /// + /// When using the `include` macro to include stretches of documentation, remember that the + /// included file still needs to be a valid rust syntax. It is also possible to + /// use the [`include_str`] macro as `#![doc = include_str!("...")]` (at the module level) or + /// `#[doc = include_str!("...")]` (at the item level) to include documentation from a plain + /// text or markdown file. /// /// # Examples /// - /// Assume there are two files in the same directory with the following - /// contents: + /// Assume there are two files in the same directory with the following contents: /// /// File 'monkeys.in': /// @@ -1461,7 +1480,6 @@ pub(crate) mod builtin { /// [the reference]: ../../../reference/attributes/derive.html #[unstable(feature = "derive_const", issue = "none")] #[rustc_builtin_macro] - #[cfg(not(bootstrap))] pub macro derive_const($item:item) { /* compiler built-in */ } @@ -1516,7 +1534,6 @@ pub(crate) mod builtin { /// Attribute macro applied to a function to register it as a handler for allocation failure. /// /// See also [`std::alloc::handle_alloc_error`](../../../std/alloc/fn.handle_alloc_error.html). - #[cfg(not(bootstrap))] #[unstable(feature = "alloc_error_handler", issue = "51540")] #[allow_internal_unstable(rustc_attrs)] #[rustc_builtin_macro] @@ -1553,7 +1570,6 @@ pub(crate) mod builtin { issue = "23416", reason = "placeholder syntax for type ascription" )] - #[cfg(not(bootstrap))] pub macro type_ascribe($expr:expr, $ty:ty) { /* compiler built-in */ } |