Document the where keyword

src/libstd/keyword_docs.rs

@@ -1651,9 +1651,100 @@ mod use_keyword {}
 //
 /// Add constraints that must be upheld to use an item.
 ///
-/// The documentation for this keyword is [not yet complete]. Pull requests welcome!
+/// `where` allows specifying constraints on lifetime and generic parameters.
+/// The [RFC] introducing `where` contains detailed informations about the
+/// keyword.
 ///
-/// [not yet complete]: https://github.com/rust-lang/rust/issues/34601
+/// # Examples
+///
+/// `where` can be used for constraints with traits:
+///
+/// ```rust
+/// fn new<T: Default>() -> T {
+///     T::default()
+/// }
+///
+/// fn new_where<T>() -> T
+/// where
+///     T: Default,
+/// {
+///     T::default()
+/// }
+///
+/// assert_eq!(0.0, new());
+/// assert_eq!(0.0, new_where());
+///
+/// assert_eq!(0, new());
+/// assert_eq!(0, new_where());
+/// ```
+///
+/// `where` can also be used for lifetimes.
+///
+/// This compiles because `longer` outlives `shorter`, thus the constraint is
+/// respected:
+///
+/// ```rust
+/// fn select<'short, 'long>(s1: &'short str, s2: &'long str, second: bool) -> &'short str
+/// where
+///     'long: 'short,
+/// {
+///     if second { s2 } else { s1 }
+/// }
+///
+/// let outer = String::from("Long living ref");
+/// let longer = &outer;
+/// {
+///     let inner = String::from("Short living ref");
+///     let shorter = &inner;
+///
+///     assert_eq!(select(shorter, longer, false), shorter);
+///     assert_eq!(select(shorter, longer, true), longer);
+/// }
+/// ```
+///
+/// On the other hand, this will not compile because the `where 'b: 'a` clause
+/// is missing: the `'b` lifetime is not known to live at least as long as `'a`
+/// which means this function cannot ensure it always returns a valid reference:
+///
+/// ```rust,compile_fail,E0623
+/// fn select<'a, 'b>(s1: &'a str, s2: &'b str, second: bool) -> &'a str
+/// {
+///     if second { s2 } else { s1 }
+/// }
+/// ```
+///
+/// `where` can also be used to express more complicated constraints that cannot
+/// be written with the `<T: Trait>` syntax:
+///
+/// ```rust
+/// fn first_or_default<I>(mut i: I) -> I::Item
+/// where
+///     I: Iterator,
+///     I::Item: Default,
+/// {
+///     i.next().unwrap_or_else(I::Item::default)
+/// }
+///
+/// assert_eq!(first_or_default(vec![1, 2, 3].into_iter()), 1);
+/// assert_eq!(first_or_default(Vec::<i32>::new().into_iter()), 0);
+/// ```
+///
+/// `where` is available anywhere generic and lifetime parameters are available,
+/// as can be seen with the [`Cow`](crate::borrow::Cow) type from the standard
+/// library:
+///
+/// ```rust
+/// # #![allow(dead_code)]
+/// pub enum Cow<'a, B>
+/// where
+///     B: 'a + ToOwned + ?Sized,
+///  {
+///     Borrowed(&'a B),
+///     Owned(<B as ToOwned>::Owned),
+/// }
+/// ```
+///
+/// [RFC]: https://github.com/rust-lang/rfcs/blob/master/text/0135-where.md
 mod where_keyword {}
 
 // 2018 Edition keywords