Rollup merge of rust-lang#43819 - frewsxcv:frewsxcv-include, r=QuietMisdreavus

Improve doc examples for `include*` macros.

Author: GuillaumeGomez

src/libstd/macros.rs

@@ -461,9 +461,26 @@ pub mod builtin {
     ///
     /// # Examples
     ///
+    /// Assume there are two files in the same directory with the following
+    /// contents:
+    ///
+    /// File 'spanish.in':
+    ///
+    /// ```text
+    /// adiós
+    /// ```
+    ///
+    /// File 'main.rs':
+    ///
     /// ```ignore (cannot-doctest-external-file-dependency)
-    /// let secret_key = include_str!("secret-key.ascii");
+    /// fn main() {
+    ///     let my_str = include_str!("spanish.in");
+    ///     assert_eq!(my_str, "adiós\n");
+    ///     print!("{}", my_str);
+    /// }
     /// ```
+    ///
+    /// Compiling 'main.rs' and running the resulting binary will print "adiós".
     #[stable(feature = "rust1", since = "1.0.0")]
     #[macro_export]
     macro_rules! include_str { ($file:expr) => ({ /* compiler built-in */ }) }
@@ -478,9 +495,26 @@ pub mod builtin {
     ///
     /// # Examples
     ///
+    /// Assume there are two files in the same directory with the following
+    /// contents:
+    ///
+    /// File 'spanish.in':
+    ///
+    /// ```text
+    /// adiós
+    /// ```
+    ///
+    /// File 'main.rs':
+    ///
     /// ```ignore (cannot-doctest-external-file-dependency)
-    /// let secret_key = include_bytes!("secret-key.bin");
+    /// fn main() {
+    ///     let bytes = include_bytes!("spanish.in");
+    ///     assert_eq!(bytes, b"adi\xc3\xb3s\n");
+    ///     print!("{}", String::from_utf8_lossy(bytes));
+    /// }
     /// ```
+    ///
+    /// Compiling 'main.rs' and running the resulting binary will print "adiós".
     #[stable(feature = "rust1", since = "1.0.0")]
     #[macro_export]
     macro_rules! include_bytes { ($file:expr) => ({ /* compiler built-in */ }) }
@@ -545,23 +579,28 @@ pub mod builtin {
     /// Assume there are two files in the same directory with the following
     /// contents:
     ///
-    /// File 'my_str.in':
+    /// File 'monkeys.in':
     ///
     /// ```ignore (only-for-syntax-highlight)
-    /// "Hello World!"
+    /// ['🙈', '🙊', '🙉']
+    ///     .iter()
+    ///     .cycle()
+    ///     .take(6)
+    ///     .collect::<String>()
     /// ```
     ///
     /// File 'main.rs':
     ///
     /// ```ignore (cannot-doctest-external-file-dependency)
     /// fn main() {
-    ///     let my_str = include!("my_str.in");
-    ///     println!("{}", my_str);
+    ///     let my_string = include!("monkeys.in");
+    ///     assert_eq!("🙈🙊🙉🙈🙊🙉", my_string);
+    ///     println!("{}", my_string);
     /// }
     /// ```
     ///
-    /// Compiling 'main.rs' and running the resulting binary will print "Hello
-    /// World!".
+    /// Compiling 'main.rs' and running the resulting binary will print
+    /// "🙈🙊🙉🙈🙊🙉".
     #[stable(feature = "rust1", since = "1.0.0")]
     #[macro_export]
     macro_rules! include { ($file:expr) => ({ /* compiler built-in */ }) }