Flesh out loops docs a little (#729)

Co-authored-by: Richard Smith <richard@metafoo.co.uk>

docs/design/control_flow/loops.md

@@ -10,18 +10,32 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 
 ## Table of contents
 
--   [`while`](#while)
--   [`for`](#for)
--   [`break`](#break)
--   [`continue`](#continue)
--   [Relevant proposals](#relevant-proposals)
+-   [Overview](#overview)
+-   [Details](#details)
+    -   [`while`](#while)
+    -   [`for`](#for)
+    -   [`break`](#break)
+    -   [`continue`](#continue)
+-   [Alternatives considered](#alternatives-considered)
+-   [References](#references)
 
 <!-- tocstop -->
 
-## `while`
+## Overview
 
-`while` statements loop for as long as the passed expression returns `True`. For
-example, this prints `0`, `1`, `2`, then `Done!`:
+Carbon provides loops using the `while` and `for` statements. Within a loop, the
+`break` and `continue` statements can be used for flow control.
+
+## Details
+
+### `while`
+
+`while` statements loop for as long as the passed expression returns `True`.
+Syntax is:
+
+> `while (` _boolean expression_ `) {` _statements_ `}`
+
+For example, this prints `0`, `1`, `2`, then `Done!`:
 
 ```carbon
 var x: Int = 0;
@@ -32,12 +46,14 @@ while (x < 3) {
 Print("Done!");
 ```
 
-> TODO: Flesh out text (currently just overview)
+### `for`
+
+`for` statements support range-based looping, typically over containers. Syntax
+is:
 
-## `for`
+> `for (` _var declaration_ `in` _expression_ `) {` _statements_ `}`
 
-`for` statements support range-based looping, typically over containers. For
-example, this prints all names in `names`:
+For example, this prints all names in `names`:
 
 ```carbon
 for (var name: String in names) {
@@ -47,13 +63,15 @@ for (var name: String in names) {
 
 `PrintNames()` prints each `String` in the `names` `List` in iteration order.
 
-> TODO: Flesh out text (currently just overview)
-
-## `break`
+### `break`
 
 The `break` statement immediately ends a `while` or `for` loop. Execution will
-resume at the end of the loop's scope. For example, this processes steps until a
-manual step is hit (if no manual step is hit, all steps are processed):
+resume at the end of the loop's scope. Syntax is:
+
+> `break;`
+
+For example, this processes steps until a manual step is hit (if no manual step
+is hit, all steps are processed):
 
 ```carbon
 for (var step: Step in steps) {
@@ -65,13 +83,14 @@ for (var step: Step in steps) {
 }
 ```
 
-> TODO: Flesh out text (currently just overview)
-
-## `continue`
+### `continue`
 
 The `continue` statement immediately goes to the next loop of a `while` or
-`for`. In a `while`, execution continues with the `while` expression. For
-example, this prints all non-empty lines of a file, using `continue` to skip
+`for`. In a `while`, execution continues with the `while` expression. Syntax is:
+
+> `continue;`
+
+For example, this prints all non-empty lines of a file, using `continue` to skip
 empty lines:
 
 ```carbon
@@ -85,12 +104,24 @@ while (!f.EOF()) {
 }
 ```
 
-> TODO: Flesh out text (currently just overview)
-
-## Relevant proposals
-
-Most discussion of design choices and alternatives may be found in relevant
-proposals.
-
--   [`while`](/proposals/p0340.md)
--   [`for`](/proposals/p0353.md)
+## Alternatives considered
+
+-   [Non-C++ syntax](/proposals/p0340.md#non-c-syntax)
+-   [Initializing variables in the `while`](/proposals/p0340.md#initializing-variables-in-the-while)
+-   `for`:
+    -   [Include semisemi `for` loops](/proposals/p0353.md#include-semisemi-for-loops)
+    -   [Multi-variable bindings](/proposals/p0353.md#multi-variable-bindings)
+    -   [`:` versus `in`](/proposals/p0618.md#-versus-in)
+-   [Optional braces](/proposals/p0623.md#optional-braces)
+-   [Optional parentheses](/proposals/p0623.md#optional-parentheses)
+
+## References
+
+-   Proposal
+    [#340: `while`](https://github.com/carbon-language/carbon-lang/pull/340)
+-   Proposal
+    [#353: `for`](https://github.com/carbon-language/carbon-lang/pull/353)
+-   Proposal
+    [#618: `var` ordering](https://github.com/carbon-language/carbon-lang/pull/618)
+-   Proposal
+    [#623: Require braces](https://github.com/carbon-language/carbon-lang/pull/623)