Show trailing commas in more places [SE-0439]

TSPL.docc/GuidedTour/GuidedTour.md

@@ -190,11 +190,6 @@ let quotation = """
   ```
 -->
 
-<!--
-  Can't show an example of indentation in the triple-quoted string above.
-  <rdar://problem/49129068> Swift code formatting damages indentation
--->
-
 Create arrays and dictionaries using brackets (`[]`),
 and access their elements by writing
 the index or key in brackets.

TSPL.docc/LanguageGuide/CollectionTypes.md

@@ -261,6 +261,23 @@ Because all values in the array literal are of the same type,
 Swift can infer that `[String]` is
 the correct type to use for the `shoppingList` variable.
 
+You can include a comma after last value in an array literal,
+which is known as a *trailing comma*:
+
+```swift
+var shoppingList = [
+    "Eggs",
+    "Milk",
+]
+```
+
+Because the trailing comma makes every line end the same way,
+it's a useful way to write arrays like the one above
+that have one value per line.
+When you change the array,
+you only need to add, remove, or reorder values ---
+you don't have to add or remove commas.
+
 ### Accessing and Modifying an Array
 
 You access and modify an array through its methods and properties,
@@ -1185,6 +1202,17 @@ and likewise all values are of the same type as each other,
 Swift can infer that `[String: String]` is
 the correct type to use for the `airports` dictionary.
 
+Like array literals,
+dictionary literals can include a trailing comma
+after the last key-value pair:
+
+```swift
+var airports = [
+    "YYZ": "Toronto Pearson",
+    "DUB": "Dublin",
+]
+```
+
 ### Accessing and Modifying a Dictionary
 
 You access and modify a dictionary through its methods and properties,

TSPL.docc/ReferenceManual/Declarations.md

@@ -1700,7 +1700,7 @@ but the new method must preserve its return type and nonreturning behavior.
 > *function-result* → **`->`** *attributes*_?_ *type* \
 > *function-body* → *code-block*
 >
-> *parameter-clause* → **`(`** **`)`** | **`(`** *parameter-list* **`)`** \
+> *parameter-clause* → **`(`** **`)`** | **`(`** *parameter-list* **`,`**_?_ **`)`** \
 > *parameter-list* → *parameter* | *parameter* **`,`** *parameter-list* \
 > *parameter* → *external-parameter-name*_?_ *local-parameter-name* *parameter-type-annotation* *default-argument-clause*_?_ \
 > *parameter* → *external-parameter-name*_?_ *local-parameter-name* *parameter-type-annotation* \

TSPL.docc/ReferenceManual/Expressions.md

@@ -677,12 +677,12 @@ in Xcode Help.
 > *literal-expression* → *literal* \
 > *literal-expression* → *array-literal* | *dictionary-literal* | *playground-literal*
 >
-> *array-literal* → **`[`** *array-literal-items*_?_ **`]`** \
-> *array-literal-items* → *array-literal-item* **`,`**_?_ | *array-literal-item* **`,`** *array-literal-items* \
+> *array-literal* → **`[`** *array-literal-items*_?_ **`,`**_?_ **`]`** \
+> *array-literal-items* → *array-literal-item* | *array-literal-item* **`,`** *array-literal-items* \
 > *array-literal-item* → *expression*
 >
-> *dictionary-literal* → **`[`** *dictionary-literal-items* **`]`** | **`[`** **`:`** **`]`** \
-> *dictionary-literal-items* → *dictionary-literal-item* **`,`**_?_ | *dictionary-literal-item* **`,`** *dictionary-literal-items* \
+> *dictionary-literal* → **`[`** *dictionary-literal-items* **`,`**_?_ **`]`** | **`[`** **`:`** **`]`** \
+> *dictionary-literal-items* → *dictionary-literal-item* | *dictionary-literal-item* **`,`** *dictionary-literal-items* \
 > *dictionary-literal-item* → *expression* **`:`** *expression*
 >
 > *playground-literal* → **`#colorLiteral`** **`(`** **`red`** **`:`** *expression* **`,`** **`green`** **`:`** *expression* **`,`** **`blue`** **`:`** *expression* **`,`** **`alpha`** **`:`** *expression* **`)`** \
@@ -1017,6 +1017,7 @@ surrounded by square brackets,
 before the list of parameters.
 If you use a capture list, you must also use the `in` keyword,
 even if you omit the parameter names, parameter types, and return type.
+The last expression in the capture list can be followed by an optional comma.
 
 The entries in the capture list are initialized
 when the closure is created.
@@ -1252,13 +1253,13 @@ see <doc:AutomaticReferenceCounting#Resolving-Strong-Reference-Cycles-for-Closur
 > *closure-signature* → *capture-list*_?_ *closure-parameter-clause* **`async`**_?_ *throws-clause*_?_ *function-result*_?_ **`in`** \
 > *closure-signature* → *capture-list* **`in`**
 >
-> *closure-parameter-clause* → **`(`** **`)`** | **`(`** *closure-parameter-list* **`)`** | *identifier-list* \
+> *closure-parameter-clause* → **`(`** **`)`** | **`(`** *closure-parameter-list* **`,`**_?_ **`)`** | *identifier-list* \
 > *closure-parameter-list* → *closure-parameter* | *closure-parameter* **`,`** *closure-parameter-list* \
 > *closure-parameter* → *closure-parameter-name* *type-annotation*_?_ \
 > *closure-parameter* → *closure-parameter-name* *type-annotation* **`...`** \
 > *closure-parameter-name* → *identifier*
 >
-> *capture-list* → **`[`** *capture-list-items* **`]`** \
+> *capture-list* → **`[`** *capture-list-items* **`,`**_?_ **`]`** \
 > *capture-list-items* → *capture-list-item* | *capture-list-item* **`,`** *capture-list-items* \
 > *capture-list-item* → *capture-specifier*_?_ *identifier* \
 > *capture-list-item* → *capture-specifier*_?_ *identifier* **`=`** *expression* \
@@ -1474,9 +1475,11 @@ A single expression inside parentheses is a parenthesized expression.
 > However, like all type aliases, `Void` is always a type ---
 > you can't use it to write an empty tuple expression.
 
+The last expression in a tuple can be followed by an optional comma.
+
 > Grammar of a tuple expression:
 >
-> *tuple-expression* → **`(`** **`)`** | **`(`** *tuple-element* **`,`** *tuple-element-list* **`)`** \
+> *tuple-expression* → **`(`** **`)`** | **`(`** *tuple-element* **`,`** *tuple-element-list* **`,`**_?_ **`)`** \
 > *tuple-element-list* → *tuple-element* | *tuple-element* **`,`** *tuple-element-list* \
 > *tuple-element* → *expression* | *identifier* **`:`** *expression*
 
@@ -2308,6 +2311,8 @@ This kind of function call expression has the following form:
 <#function name#>(<#argument name 1#>: <#argument value 1#>, <#argument name 2#>: <#argument value 2#>)
 ```
 
+The last argument in parentheses can be followed by an optional comma.
+
 A function call expression can include trailing closures
 in the form of closure expressions immediately after the closing parenthesis.
 The trailing closures are understood as arguments to the function,
@@ -2472,6 +2477,8 @@ the old right-to-left ordering is used
 and the compiler generates a warning.
 A future version of Swift will always use the left-to-right ordering.
 
+<!-- FIXME: What future version? -->
+
 ```swift
 typealias Callback = (Int) -> Int
 func someFunction(firstClosure: Callback? = nil,
@@ -2643,7 +2650,7 @@ avoid using `&` instead of using the unsafe APIs explicitly.
 > *function-call-expression* → *postfix-expression* *function-call-argument-clause* \
 > *function-call-expression* → *postfix-expression* *function-call-argument-clause*_?_ *trailing-closures*
 >
-> *function-call-argument-clause* → **`(`** **`)`** | **`(`** *function-call-argument-list* **`)`** \
+> *function-call-argument-clause* → **`(`** **`)`** | **`(`** *function-call-argument-list* **`,`**_?_ **`)`** \
 > *function-call-argument-list* → *function-call-argument* | *function-call-argument* **`,`** *function-call-argument-list* \
 > *function-call-argument* → *expression* | *identifier* **`:`** *expression* \
 > *function-call-argument* → *operator* | *identifier* **`:`** *operator*

TSPL.docc/ReferenceManual/GenericParametersAndArguments.md

@@ -99,6 +99,9 @@ simpleMax(3.14159, 2.71828) // T is inferred to be Double
   Tracking bug is <rdar://problem/35301593>
 -->
 
+The last generic parameter in a generic parameter list
+can be followed by an optional comma.
+
 ### Integer Generic Parameters
 
 An *integer generic parameter*
@@ -273,7 +276,7 @@ see <doc:Generics#Generic-Where-Clauses>.
 
 > Grammar of a generic parameter clause:
 >
-> *generic-parameter-clause* → **`<`** *generic-parameter-list* **`>`** \
+> *generic-parameter-clause* → **`<`** *generic-parameter-list* **`,`**_?_ **`>`** \
 > *generic-parameter-list* → *generic-parameter* | *generic-parameter* **`,`** *generic-parameter-list* \
 > *generic-parameter* → *type-name* \
 > *generic-parameter* → *type-name* **`:`** *type-identifier* \
@@ -351,13 +354,22 @@ let arrayOfArrays: Array<Array<Int>> = [[1, 2, 3], [4, 5, 6], [7, 8, 9]]
   ```
 -->
 
+The last type argument in a generic argument list
+can be followed by an optional comma.
+<!--
+XXX TR: Please confirm.
+The SE proposal shows only generic parameter lists,
+but the rule that trailing commas are allowed inside matching brackets
+should allow them here also.
+-->
+
 As mentioned in <doc:GenericParametersAndArguments#Generic-Parameter-Clause>,
 you don't use a generic argument clause to specify the type arguments
 of a generic function or initializer.
 
 > Grammar of a generic argument clause:
 >
-> *generic-argument-clause* → **`<`** *generic-argument-list* **`>`** \
+> *generic-argument-clause* → **`<`** *generic-argument-list* **`,`**_?_ **`>`** \
 > *generic-argument-list* → *generic-argument* | *generic-argument* **`,`** *generic-argument-list* \
 > *generic-argument* → *type* | *signed-integer-literal*