Rollup merge of #62462 - JohnTitor:document-while, r=Centril

Document `while` keyword

This is a rework of #60761.
Closes #60736

r? @dtolnay

1 files changed, 56 insertions, 9 deletions

diff --git a/src/libstd/keyword_docs.rs b/src/libstd/keyword_docs.rs
index d133c2f5cb1..d18fcb4a1da 100644
--- a/src/libstd/keyword_docs.rs
+++ b/src/libstd/keyword_docs.rs
@@ -608,6 +608,62 @@ mod in_keyword { }
 /// [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.
@@ -922,15 +978,6 @@ mod use_keyword { }
 /// [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")]