Auto merge of rust-lang#12526 - kpreid:patch-2, r=blyxyas

Mention `size_hint()` effect in `flat_map_option` lint documentation.

The previous documentation for `flat_map_option` mentioned only readability benefits, but there is also at least one performance benefit: the `size_hint()` upper bound is preserved, whereas `flat_map().size_hint()` is always `(0, None)`.

Program demonstrating this difference:

```rust
fn main() {
    let evens = |i| if i % 2 == 0 { Some(i) } else { None };

    dbg!(
        [1, 2, 3].iter().flat_map(evens).size_hint(),
        [1, 2, 3].iter().filter_map(evens).size_hint(),
    );
}
```

changelog: [`flat_map_option`]: Mention the benefit to `size_hint()`.

Author: bors

clippy_lints/src/methods/mod.rs

@@ -231,8 +231,12 @@ declare_clippy_lint! {
     /// used instead.
     ///
     /// ### Why is this bad?
-    /// When applicable, `filter_map()` is more clear since it shows that
-    /// `Option` is used to produce 0 or 1 items.
+    /// `filter_map()` is known to always produce 0 or 1 output items per input item,
+    /// rather than however many the inner iterator type produces.
+    /// Therefore, it maintains the upper bound in `Iterator::size_hint()`,
+    /// and communicates to the reader that the input items are not being expanded into
+    /// multiple output items without their having to notice that the mapping function
+    /// returns an `Option`.
     ///
     /// ### Example
     /// ```no_run