Clarify the behaviour of Pattern when used with methods like str::con…

…tains

src/libcore/str/pattern.rs

@@ -60,6 +60,43 @@ use crate::slice::memchr;
 /// The trait itself acts as a builder for an associated
 /// `Searcher` type, which does the actual work of finding
 /// occurrences of the pattern in a string.
+///
+/// Depending on the type of the pattern, the behaviour of methods like
+/// [`str::find`] and [`str::contains`] can change. The table below describes
+/// some of those behaviours.
+///
+/// | Pattern type             | Match condition                           |
+/// |--------------------------|-------------------------------------------|
+/// | `&str`                   | is substring                              |
+/// | `char`                   | is contained in string                    |
+/// | `&[char]                 | any char in slice is contained in string  |
+/// | `F: FnMut(char) -> bool` | `F` returns `true` for a char in string   |
+/// | `&&str`                  | is substring                              |
+/// | `&String`                | is substring                              |
+///
+/// # Examples
+/// ```
+/// // &str
+/// assert_eq!("abaaa".find("ba"), Some(1));
+/// assert_eq!("abaaa".find("bac"), None);
+///
+/// // char
+/// assert_eq!("abaaa".find('a'), Some(0));
+/// assert_eq!("abaaa".find('b'), Some(1));
+/// assert_eq!("abaaa".find('c'), None);
+///
+/// // &[char]
+/// assert_eq!("ab".find(&['b', 'a'][..]), Some(0));
+/// assert_eq!("abaaa".find(&['a', 'z'][..]), Some(0));
+/// assert_eq!("abaaa".find(&['c', 'd'][..]), None);
+///
+/// // FnMut(char) -> bool
+/// assert_eq!("abcdef_z".find(|ch| ch > 'd' && ch < 'y'), Some(4));
+/// assert_eq!("abcddd_z".find(|ch| ch > 'd' && ch < 'y'), None);
+/// ```
+///
+/// [`str::find`]: ../../../std/primitive.str.html#method.find
+/// [`str::contains`]: ../../../std/primitive.str.html#method.contains
 pub trait Pattern<'a>: Sized {
     /// Associated searcher for this pattern
     type Searcher: Searcher<'a>;