doc: clarify meaning of SetMatches::len

It is really unfortunate, but SetMatches::len and
SetMatcher::iter().count() do not correspond go the same thing. It's not
clear why I even added the SetMatches::len method in the first place,
but it always returns the number of regexes in the set, and not the
number of regexes that matched.

We can't change the name (or remove the method) obviously, but we do add
a warning to the docs.

Fixes #625

Author: BurntSushi

src/re_set.rs

@@ -321,6 +321,11 @@ impl SetMatches {
     }
 
     /// The total number of regexes in the set that created these matches.
+    ///
+    /// **WARNING:** This always returns the same value as [`RegexSet::len`].
+    /// In particular, it does *not* return the number of elements yielded by
+    /// [`SetMatches::iter`]. The only way to determine the total number of
+    /// matched regexes is to iterate over them.
     pub fn len(&self) -> usize {
         self.matches.len()
     }