Improve docs with examples

Author: nyurik

clippy_lints/src/format_args.rs

@@ -85,6 +85,26 @@ declare_clippy_lint! {
     /// # let foo = 42;
     /// format!("{foo}");
     /// ```
+    ///
+    /// ### Supported cases
+    ///
+    /// code | suggestion | comment
+    /// ---|---|---
+    /// `print!("{}", var)` | `print!("{var}")` |  simple variables
+    /// `print!("{0}", var)` | `print!("{var}")` |  positional variables
+    /// `print!("{v}", v=var)` | `print!("{var}")` |  named variables
+    /// `print!("{0} {0}", var)` | `print!("{var} {var}")` |  aliased variables
+    /// `print!("{0:1$}", var, width)` | `print!("{var:width$}")` |  width support
+    /// `print!("{0:.1$}", var, prec)` | `print!("{var:.prec$}")` |  precision support
+    /// `print!("{:.*}", prec, var)` | `print!("{var:.prec$}")` |  asterisk support
+    ///
+    /// ### Unsupported cases
+    ///
+    /// code | suggestion | comment
+    /// ---|---|---
+    /// `print!("{0}={1}", var, 1+2)` | `print!("{var}={0}", 1+2)` | Format string uses an indexed argument that cannot be inlined.  Supporting this case requires re-indexing of the format string.
+    ///
+    /// changelog: [`needless-format-args`]: A new lint to inline format arguments, i.e. `print!("{}", var)` into `print!("{var}")`
     #[clippy::version = "1.64.0"]
     pub NEEDLESS_FORMAT_ARGS,
     nursery,

src/docs/needless_format_args.txt

@@ -14,4 +14,24 @@ format!("{}", foo);
 Use instead:
 ```
 format!("{foo}");
-```
+```
+
+### Supported cases
+
+code | suggestion | comment
+---|---|---
+`print!("{}", var)` | `print!("{var}")` |  simple variables
+`print!("{0}", var)` | `print!("{var}")` |  positional variables
+`print!("{v}", v=var)` | `print!("{var}")` |  named variables
+`print!("{0} {0}", var)` | `print!("{var} {var}")` |  aliased variables
+`print!("{0:1$}", var, width)` | `print!("{var:width$}")` |  width support
+`print!("{0:.1$}", var, prec)` | `print!("{var:.prec$}")` |  precision support
+`print!("{:.*}", prec, var)` | `print!("{var:.prec$}")` |  asterisk support
+
+### Unsupported cases
+
+code | suggestion | comment
+---|---|---
+`print!("{0}={1}", var, 1+2)` | `print!("{var}={0}", 1+2)` | Format string uses an indexed argument that cannot be inlined.  Supporting this case requires re-indexing of the format string.
+
+changelog: [`needless-format-args`]: A new lint to inline format arguments, i.e. `print!("{}", var)` into `print!("{var}")`