Simplify introductory examples

Author: nik-rev

README.md

@@ -56,32 +56,48 @@ int main(int argc, char **argv) {
 
 ## Composition
 
-[`docstr!`](https://docs.rs/docstr/0.4.9/docstr/macro.docstr.html) can pass the generated string to any macro:
+[`docstr!`](https://docs.rs/docstr/0.4.9/docstr/macro.docstr.html) can pass the generated string to any macro. This example shows the string being forwarded to the [`format!`](https://doc.rust-lang.org/stable/alloc/macro.format.html) macro:
 
 ```rust
-use docstr::docstr;
-
-let age = 21;
 let name = "Bob";
-let colors = ["red", "green", "blue"];
+let age = 21;
 
 let greeting: String = docstr!(format!
-                             //^^^^^^^ the generated string is passed to `format!`
-                             //        as the 1st argument
     /// Hello, my name is {name}.
-    /// I am {age} years old!
-    ///
-    /// My favorite color is: {}
+    /// I am {} years old!
+    age
+);
+
+assert_eq!(greeting, "\
+Hello, my name is Bob.
+I am 21 years old!");
+```
+
+This is great because there’s just a single macro, `docstr!`, that can do anything. No need for `docstr_format!`, `docstr_println!`, `docstr_write!`, etc.
 
-    // anything after the doc comments is passed directly at the end
-    colors[1]
+### How composition works
+
+If the first argument to `docstr!` is a path to a macro, that macro will be called. This invocation:
+
+```rust
+let greeting: String = docstr!(format!
+    /// Hello, my name is {name}.
+    /// I am {} years old!
+    age
 );
-//^ above expands to: format!("...", colors[1])
+```
+
+Is equivalent to this:
 
-assert_eq!(greeting, "Hello, my name is Bob.\nI am 21 years old!\n\nMy favorite color is: green");
+```rust
+let greeting: String = format!("\
+Hello, my name is {name}.
+I am {} years old!"
+    age,
+);
 ```
 
-Injecting arguments before the generated string is also possible.
+You can inject arguments before the format string:
 
 ```rust
 docstr!(write! w

src/lib.rs

@@ -39,32 +39,50 @@
 //!
 //! # Composition
 //!
-//! [`docstr!`](crate::docstr) can pass the generated string to any macro:
+//! [`docstr!`](crate::docstr) can pass the generated string to any macro. This example shows the string being forwarded to the [`format!`] macro:
 //!
-//! ```rust
-//! use docstr::docstr;
-//!
-//! let age = 21;
+//! ```
+//! # use docstr::docstr;
 //! let name = "Bob";
-//! let colors = ["red", "green", "blue"];
+//! let age = 21;
 //!
 //! let greeting: String = docstr!(format!
-//!                              //^^^^^^^ the generated string is passed to `format!`
-//!                              //        as the 1st argument
 //!     /// Hello, my name is {name}.
-//!     /// I am {age} years old!
-//!     ///
-//!     /// My favorite color is: {}
+//!     /// I am {} years old!
+//!     age
+//! );
+//!
+//! assert_eq!(greeting, "\
+//! Hello, my name is Bob.
+//! I am 21 years old!");
+//! ```
 //!
-//!     // anything after the doc comments is passed directly at the end
-//!     colors[1]
+//! This is great because there's just a single macro, `docstr!`, that can do anything. No need for `docstr_format!`, `docstr_println!`, `docstr_write!`, etc.
+//!
+//! ## How composition works
+//!
+//! If the first argument to `docstr!` is a path to a macro, that macro will be called. This invocation:
+//!
+//! ```
+//! # use docstr::docstr;
+//! let greeting: String = docstr!(format!
+//!     /// Hello, my name is {name}.
+//!     /// I am {} years old!
+//!     age
 //! );
-//! //^ above expands to: format!("...", colors[1])
+//! ```
+//!
+//! Is equivalent to this:
 //!
-//! assert_eq!(greeting, "Hello, my name is Bob.\nI am 21 years old!\n\nMy favorite color is: green");
+//! ```
+//! let greeting: String = format!("\
+//! Hello, my name is {name}.
+//! I am {} years old!"
+//!     age,
+//! );
 //! ```
 //!
-//! Injecting arguments before the generated string is also possible.
+//! You can inject arguments before the format string:
 //!
 //! ```rust
 //! # let mut w = String::new();