Add keyword docs for `loop`.

1 files changed, 45 insertions, 0 deletions

diff --git a/src/libstd/keyword_docs.rs b/src/libstd/keyword_docs.rs
index d2a22334a95..63df5401b92 100644
--- a/src/libstd/keyword_docs.rs
+++ b/src/libstd/keyword_docs.rs
@@ -576,6 +576,51 @@ mod impl_keyword { }
 /// [Reference]: https://doc.rust-lang.org/reference/statements.html#let-statements
 mod let_keyword { }
 
+#[doc(keyword = "loop")]
+//
+/// The loop-defining keyword.
+///
+/// `loop` is used to define the simplest kind of loop supported in Rust. It runs the code inside
+/// it until the code uses `break` or the program exits.
+///
+/// ```rust
+/// loop {
+///     println!("hello world forever!");
+///     # break;
+/// }
+///
+/// let mut i = 0;
+/// loop {
+///     println!("i is {}", i);
+///     if i > 10 {
+///         break;
+///     }
+///     i += 1;
+/// }
+/// ```
+///
+/// Unlike the other kinds of loops in Rust (`while`, `while let`, and `for`), loops can be used as
+/// expressions that return values via `break`.
+///
+/// ```rust
+/// let mut i = 1;
+/// let something = loop {
+///     i *= 2;
+///     if i > 100 {
+///         break i;
+///     }
+/// };
+/// assert_eq!(something, 128);
+/// ```
+///
+/// Every `break` in a loop has to have the same type. When it's not explicitly giving something,
+/// `break;` returns `()`.
+///
+/// For more information on `loop` and loops in general, see the [Reference].
+///
+/// [Reference]: https://doc.rust-lang.org/reference/expressions/loop-expr.html
+mod loop_keyword { }
+
 #[doc(keyword = "struct")]
 //
 /// The keyword used to define structs.