/// [Reference]: ../reference/statements.html#let-statements
mod let_keyword { }
+#[doc(keyword = "while")]
+//
+/// Loop while a condition is upheld.
+///
+/// A `while` expression is used for predicate loops. The `while` expression runs the conditional
+/// expression before running the loop body, then runs the loop body if the conditional
+/// expression evaluates to `true`, or exits the loop otherwise.
+///
+/// ```rust
+/// let mut counter = 0;
+///
+/// while counter < 10 {
+/// println!("{}", counter);
+/// counter += 1;
+/// }
+/// ```
+///
+/// Like the [`for`] expression, we can use `break` and `continue`. A `while` expression
+/// cannot break with a value and always evaluates to `()` unlike [`loop`].
+///
+/// ```rust
+/// let mut i = 1;
+///
+/// while i < 100 {
+/// i *= 2;
+/// if i == 64 {
+/// break; // Exit when `i` is 64.
+/// }
+/// }
+/// ```
+///
+/// As `if` expressions have their pattern matching variant in `if let`, so too do `while`
+/// expressions with `while let`. The `while let` expression matches the pattern against the
+/// expression, then runs the loop body if pattern matching succeeds, or exits the loop otherwise.
+/// We can use `break` and `continue` in `while let` expressions just like in `while`.
+///
+/// ```rust
+/// let mut counter = Some(0);
+///
+/// while let Some(i) = counter {
+/// if i == 10 {
+/// counter = None;
+/// } else {
+/// println!("{}", i);
+/// counter = Some (i + 1);
+/// }
+/// }
+/// ```
+///
+/// For more information on `while` and loops in general, see the [reference].
+///
+/// [`for`]: keyword.for.html
+/// [`loop`]: keyword.loop.html
+/// [reference]: ../reference/expressions/loop-expr.html#predicate-loops
+mod while_keyword { }
+
#[doc(keyword = "loop")]
//
/// Loop indefinitely.
/// [not yet complete]: https://github.com/rust-lang/rust/issues/34601
mod where_keyword { }
-#[doc(keyword = "while")]
-//
-/// Loop while a condition is upheld.
-///
-/// The documentation for this keyword is [not yet complete]. Pull requests welcome!
-///
-/// [not yet complete]: https://github.com/rust-lang/rust/issues/34601
-mod while_keyword { }
-
// 2018 Edition keywords
#[unstable(feature = "async_await", issue = "50547")]