About impl Debug

I checked that the examples are compilable.

Author: Philippe-Cholet

CONTRIBUTING.md

@@ -67,6 +67,70 @@ Additionally,
 An adaptor might use the inner iterator specializations for its own specializations.
 
 ## Additional implementations
+### The [`Debug`](https://doc.rust-lang.org/std/fmt/trait.Debug.html) implementation
+All our iterators should implement `Debug`.
+
+When one of the field is not debuggable (such as _functions_), you must not derive `Debug`.
+Instead, manually implement it and _ignore this field_ in our helper macro `debug_fmt_fields`.
+
+<details>
+<summary>4 examples (click to expand)</summary>
+
+```rust
+use std::fmt;
+
+/* ===== Simple derive. ===== */
+#[derive(Debug)]
+struct Name1<I> {
+    iter: I,
+}
+
+/* ===== With an unclonable field. ===== */
+struct Name2<I, F> {
+    iter: I,
+    func: F,
+}
+
+// No `F: Debug` bound and the field `func` is ignored.
+impl<I: fmt::Debug, F> fmt::Debug for Name2<I, F> {
+    // it defines the `fmt` function from a struct name and the fields you want to debug.
+    debug_fmt_fields!(Name2, iter);
+}
+
+/* ===== With an unclonable field, but another bound to add. ===== */
+struct Name3<I: Iterator, F> {
+    iter: I,
+    item: Option<I::Item>,
+    func: F,
+}
+
+// Same about `F` and `func`, similar about `I` but we must add the `I::Item: Debug` bound.
+impl<I: Iterator + fmt::Debug, F> fmt::Debug for Name3<I, F>
+where
+    I::Item: fmt::Debug,
+{
+    debug_fmt_fields!(Name3, iter, item);
+}
+
+/* ===== With an unclonable field for which we can provide some information. ===== */
+struct Name4<I, F> {
+    iter: I,
+    func: Option<F>,
+}
+
+// If ignore a field is not good enough, implement Debug fully manually.
+impl<I: fmt::Debug, F> fmt::Debug for Name4<I, F> {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        let func = if self.func.is_some() { "Some(_)" } else { "None" };
+        f.debug_struct("Name4")
+            .field("iter", &self.iter)
+            .field("func", &func)
+            .finish()
+    }
+}
+```
+</details>
+
 ### When to implement [`std::iter::FusedIterator`](https://doc.rust-lang.org/std/iter/trait.FusedIterator.html)
 This trait should be implemented _by all iterators that always return `None` after returning `None` once_, because it allows to optimize `Iterator::fuse()`.