Auto merge of rust-lang#75949 - vext01:filter-docs, r=jyn514

Try to improve the documentation of `filter()` and `filter_map()`.

I believe the documentation is currently a little misleading.

For example, in the docs for `filter()`:

> If the closure returns `false`, it will try again, and call the closure on
> the next element, seeing if it passes the test.

This kind of implies that if the closure returns true then we *don't* "try
again" and no further elements are considered. In actuality that's not the
case, every element is tried regardless of what happened with the previous
element.

This change tries to clarify that by removing the uses of "try again"
altogether.

Author: bors

library/core/src/iter/traits/iterator.rs

@@ -648,11 +648,9 @@ pub trait Iterator {
     /// Creates an iterator which uses a closure to determine if an element
     /// should be yielded.
     ///
-    /// The closure must return `true` or `false`. `filter()` creates an
-    /// iterator which calls this closure on each element. If the closure
-    /// returns `true`, then the element is returned. If the closure returns
-    /// `false`, it will try again, and call the closure on the next element,
-    /// seeing if it passes the test.
+    /// Given an element the closure must return `true` or `false`. The returned
+    /// iterator will yield only the elements for which the closure returns
+    /// true.
     ///
     /// # Examples
     ///
@@ -719,24 +717,16 @@ pub trait Iterator {
 
     /// Creates an iterator that both filters and maps.
     ///
-    /// The closure must return an [`Option<T>`]. `filter_map` creates an
-    /// iterator which calls this closure on each element. If the closure
-    /// returns [`Some(element)`][`Some`], then that element is returned. If the
-    /// closure returns [`None`], it will try again, and call the closure on the
-    /// next element, seeing if it will return [`Some`].
+    /// The returned iterator yields only the `value`s for which the supplied
+    /// closure returns `Some(value)`.
     ///
-    /// Why `filter_map` and not just [`filter`] and [`map`]? The key is in this
-    /// part:
+    /// `filter_map` can be used to make chains of [`filter`] and [`map`] more
+    /// concise. The example below shows how a `map().filter().map()` can be
+    /// shortened to a single call to `filter_map`.
     ///
     /// [`filter`]: Iterator::filter
     /// [`map`]: Iterator::map
     ///
-    /// > If the closure returns [`Some(element)`][`Some`], then that element is returned.
-    ///
-    /// In other words, it removes the [`Option<T>`] layer automatically. If your
-    /// mapping is already returning an [`Option<T>`] and you want to skip over
-    /// [`None`]s, then `filter_map` is much, much nicer to use.
-    ///
     /// # Examples
     ///
     /// Basic usage: