From 0c43b42b0cd1823388418504e84f3c4fec6f33b9 Mon Sep 17 00:00:00 2001 From: Gijs Burghoorn Date: Wed, 4 Jan 2023 16:07:33 +0100 Subject: [PATCH 1/4] Improve include macro documentation --- library/core/src/macros/mod.rs | 64 +++++++++++++++++++++++----------- 1 file changed, 44 insertions(+), 20 deletions(-) diff --git a/library/core/src/macros/mod.rs b/library/core/src/macros/mod.rs index cfc1cabe229e5..b20e60ad96d17 100644 --- a/library/core/src/macros/mod.rs +++ b/library/core/src/macros/mod.rs @@ -1312,28 +1312,52 @@ pub(crate) mod builtin { /* compiler built-in */ }; } - + /// 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. - /// - /// 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. + ///
+ /// 
+    ///
+    /// **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).
+    ///
+    ///
+ ///
+ /// + /// If the included file is parsed as an expression, it is placed in the surrounding code + /// [unhygienically](https://doc.rust-lang.org/reference/macros-by-example.html#hygiene). 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. + /// + /// 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. /// + /// # 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': - /// + /// /// ```ignore (only-for-syntax-highlight) /// ['🙈', '🙊', '🙉'] /// .iter() @@ -1341,9 +1365,9 @@ pub(crate) mod builtin { /// .take(6) /// .collect::() /// ``` - /// + /// /// File 'main.rs': - /// + /// /// ```ignore (cannot-doctest-external-file-dependency) /// fn main() { /// let my_string = include!("monkeys.in"); @@ -1351,7 +1375,7 @@ pub(crate) mod builtin { /// println!("{my_string}"); /// } /// ``` - /// + /// /// Compiling 'main.rs' and running the resulting binary will print /// "🙈🙊🙉🙈🙊🙉". #[stable(feature = "rust1", since = "1.0.0")] From eb2980c7f1df7d4c461837daeca4c14eeea80429 Mon Sep 17 00:00:00 2001 From: Gijs Burghoorn Date: Wed, 4 Jan 2023 16:18:34 +0100 Subject: [PATCH 2/4] Tidy up whitespace --- library/core/src/macros/mod.rs | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/library/core/src/macros/mod.rs b/library/core/src/macros/mod.rs index b20e60ad96d17..ff80d1160f65e 100644 --- a/library/core/src/macros/mod.rs +++ b/library/core/src/macros/mod.rs @@ -1312,7 +1312,7 @@ pub(crate) mod builtin { /* compiler built-in */ }; } - + /// Parses a file as an expression or an item according to the context. /// ///
@@ -1328,19 +1328,19 @@ pub(crate) mod builtin { /// /// ///
- /// + /// /// If the included file is parsed as an expression, it is placed in the surrounding code /// [unhygienically](https://doc.rust-lang.org/reference/macros-by-example.html#hygiene). 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. - /// + /// /// 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. /// /// # 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` @@ -1351,13 +1351,13 @@ pub(crate) mod builtin { /// 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: - /// + /// /// File 'monkeys.in': - /// + /// /// ```ignore (only-for-syntax-highlight) /// ['🙈', '🙊', '🙉'] /// .iter() @@ -1365,9 +1365,9 @@ pub(crate) mod builtin { /// .take(6) /// .collect::() /// ``` - /// + /// /// File 'main.rs': - /// + /// /// ```ignore (cannot-doctest-external-file-dependency) /// fn main() { /// let my_string = include!("monkeys.in"); @@ -1375,7 +1375,7 @@ pub(crate) mod builtin { /// println!("{my_string}"); /// } /// ``` - /// + /// /// Compiling 'main.rs' and running the resulting binary will print /// "🙈🙊🙉🙈🙊🙉". #[stable(feature = "rust1", since = "1.0.0")] From c30f7c99809b99626667e6aa4ae0ab4d4cbbd055 Mon Sep 17 00:00:00 2001 From: Gijs Burghoorn Date: Thu, 5 Jan 2023 17:09:05 +0100 Subject: [PATCH 3/4] Better phrasing for hygiene of include macro --- library/core/src/macros/mod.rs | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/library/core/src/macros/mod.rs b/library/core/src/macros/mod.rs index ff80d1160f65e..be13317008c05 100644 --- a/library/core/src/macros/mod.rs +++ b/library/core/src/macros/mod.rs @@ -1329,10 +1329,11 @@ pub(crate) mod builtin { /// /// /// - /// If the included file is parsed as an expression, it is placed in the surrounding code - /// [unhygienically](https://doc.rust-lang.org/reference/macros-by-example.html#hygiene). 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. + /// 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, From ae667be0f6017002587a28be257238655d34fa54 Mon Sep 17 00:00:00 2001 From: Gijs Burghoorn Date: Fri, 6 Jan 2023 13:20:58 +0100 Subject: [PATCH 4/4] Remove HTML tags around warning --- library/core/src/macros/mod.rs | 6 ------ 1 file changed, 6 deletions(-) diff --git a/library/core/src/macros/mod.rs b/library/core/src/macros/mod.rs index be13317008c05..3b026bc0e0f38 100644 --- a/library/core/src/macros/mod.rs +++ b/library/core/src/macros/mod.rs @@ -1315,9 +1315,6 @@ pub(crate) mod builtin { /// Parses a file as an expression or an item according to the context. /// - ///
- /// 
-    ///
     /// **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
@@ -1326,9 +1323,6 @@ pub(crate) mod builtin {
     /// 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