From c3f335b2cd0cd30dbbfb0597468a54e61e8de90b Mon Sep 17 00:00:00 2001
From: Philippe-Cholet <44676486+Philippe-Cholet@users.noreply.github.com>
Date: Fri, 17 May 2024 12:12:28 +0200
Subject: [PATCH 1/2] `Itertools::format[_with]` docs mention it can panic if
 used in logging macros

I failed to make the (invisible) macro usable as `tracing::info!` with some private module. Renamed it `tracing_info` instead.
I add `should_panic` but checked it panics for the right reason.
---
 src/lib.rs | 43 +++++++++++++++++++++++++++++++++++++++----
 1 file changed, 39 insertions(+), 4 deletions(-)

diff --git a/src/lib.rs b/src/lib.rs
index b98e03f29..592b59deb 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -2326,8 +2326,6 @@ pub trait Itertools: Iterator {
     /// All elements are formatted (any formatting trait)
     /// with `sep` inserted between each element.
     ///
-    /// **Panics** if the formatter helper is formatted more than once.
-    ///
     /// ```
     /// use itertools::Itertools;
     ///
@@ -2336,6 +2334,26 @@ pub trait Itertools: Iterator {
     ///     format!("{:.2}", data.iter().format(", ")),
     ///            "1.10, 2.72, -3.00");
     /// ```
+    ///
+    /// # Panics
+    /// When the formatter helper is formatted more than once.
+    ///
+    /// ⚠ This can happen unexpectedly and be hard to debug if used in
+    /// _macros of some logging frameworks_ like `tracing`! ⚠
+    ///
+    /// ```should_panic
+    /// # macro_rules! tracing_info {
+    /// #     ($s:literal, $arg0:expr) => {
+    /// #         let arg = $arg0;
+    /// #         let _1 = format!($s, arg);
+    /// #         let _2 = format!($s, arg);
+    /// #     };
+    /// # }
+    /// use itertools::Itertools;
+    ///
+    /// let data = [1.1, 2.71828, -3.];
+    /// tracing_info!("values: {:.2}", data.iter().format(", "));
+    /// ```
     fn format(self, sep: &str) -> Format<Self>
     where
         Self: Sized,
@@ -2354,8 +2372,6 @@ pub trait Itertools: Iterator {
     /// Using `&format_args!(...)` is the most versatile way to apply custom
     /// element formatting. The callback can be called multiple times if needed.
     ///
-    /// **Panics** if the formatter helper is formatted more than once.
-    ///
     /// ```
     /// use itertools::Itertools;
     ///
@@ -2372,8 +2388,27 @@ pub trait Itertools: Iterator {
     ///                              });
     /// assert_eq!(format!("{}", matrix_formatter),
     ///            "1, 2, 3\n4, 5, 6");
+    /// ```
     ///
+    /// # Panics
+    /// When the formatter helper is formatted more than once.
+    ///
+    /// ⚠ This can happen unexpectedly and be hard to debug if used in
+    /// _macros of some logging frameworks_ like `tracing`! ⚠
+    ///
+    /// ```should_panic
+    /// # macro_rules! tracing_info {
+    /// #     ($s:literal, $arg0:expr) => {
+    /// #         let arg = $arg0;
+    /// #         let _1 = format!($s, arg);
+    /// #         let _2 = format!($s, arg);
+    /// #     };
+    /// # }
+    /// use itertools::Itertools;
     ///
+    /// let data = [1.1, 2.71828, -3.];
+    /// let data_formatter = data.iter().format_with(", ", |elt, f| f(&format_args!("{:.2}", elt)));
+    /// tracing_info!("values: {:.2}", data_formatter);
     /// ```
     fn format_with<F>(self, sep: &str, format: F) -> FormatWith<Self, F>
     where

From df96c73aeb36e4755cb9fdcec1df1941a59cde63 Mon Sep 17 00:00:00 2001
From: Philippe-Cholet <44676486+Philippe-Cholet@users.noreply.github.com>
Date: Tue, 18 Jun 2024 10:36:32 +0200
Subject: [PATCH 2/2] =?UTF-8?q?"Warning=20div"=20instead=20of=20emoji=20"?=
 =?UTF-8?q?=E2=9A=A0"?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Markdown can not be used inside it.
It renders well in the documentation and in my IDE (Sublime Text: orange text).
---
 src/lib.rs | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/src/lib.rs b/src/lib.rs
index 592b59deb..146beb32a 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -2338,8 +2338,8 @@ pub trait Itertools: Iterator {
     /// # Panics
     /// When the formatter helper is formatted more than once.
     ///
-    /// ⚠ This can happen unexpectedly and be hard to debug if used in
-    /// _macros of some logging frameworks_ like `tracing`! ⚠
+    /// <div class="warning">This can happen unexpectedly and be hard to debug if used in
+    /// <i>macros of some logging frameworks</i> like <code>tracing</code>!</div>
     ///
     /// ```should_panic
     /// # macro_rules! tracing_info {
@@ -2393,8 +2393,8 @@ pub trait Itertools: Iterator {
     /// # Panics
     /// When the formatter helper is formatted more than once.
     ///
-    /// ⚠ This can happen unexpectedly and be hard to debug if used in
-    /// _macros of some logging frameworks_ like `tracing`! ⚠
+    /// <div class="warning">This can happen unexpectedly and be hard to debug if used in
+    /// <i>macros of some logging frameworks</i> like <code>tracing</code>!</div>
     ///
     /// ```should_panic
     /// # macro_rules! tracing_info {