Add discussion of 'some' on parameter types [SE-0341] (#350)

Fixes: rdar://143326925

Author: amartini51

TSPL.docc/LanguageGuide/Generics.md

@@ -286,9 +286,21 @@ However, when there isn't a meaningful relationship between them,
 it's traditional to name them using single letters such as `T`, `U`, and `V`,
 such as `T` in the `swapTwoValues(_:_:)` function above.
 
-> Note: Always give type parameters upper camel case names
-> (such as `T` and `MyTypeParameter`)
-> to indicate that they're a placeholder for a *type*, not a value.
+Use upper camel case names for type parameters,
+like `T` and `MyTypeParameter`,
+to indicate that they're a placeholder for a *type*, not a value.
+
+> Note:
+> If you don't need to name a type parameter
+> and its generic type constraints are simple,
+> there's an alternate, lightweight syntax you can use instead,
+> as described in <doc:OpaqueTypes#Opaque-Parameter-Types>.
+<!--
+Comparison between this syntax and the lightweight syntax
+is in the Opaque Types chapter, not here ---
+the reader hasn't learned about constraints yet,
+so it wouldn't make sense to list what is/isn't supported.
+-->
 
 ## Generic Types
 

TSPL.docc/LanguageGuide/OpaqueTypes.md

@@ -921,6 +921,67 @@ which means that the type of `twelve` is also inferred to be `Int`.
   }
 -->
 
+
+## Opaque Parameter Types
+
+In addition to writing `some` to return an opaque type,
+you can also write `some` in the type for a parameter
+to a function, subscript, or initializer.
+However, when you write `some` in a parameter type
+that's just a shorter syntax for generics, not an opaque type.
+For example,
+both of the functions below are equivalent:
+
+```swift
+func drawTwiceGeneric<SomeShape: Shape>(_ shape: SomeShape) -> String {
+    let drawn = shape.draw()
+    return drawn + "\n" + drawn
+}
+
+func drawTwiceSome(_ shape: some Shape) -> String {
+    let drawn = shape.draw()
+    return drawn + "\n" + drawn
+}
+```
+
+The `drawTwiceGeneric(_:)` function
+declares a generic type parameter named `SomeShape`,
+with a constraint that requires `SomeShape` to conform to the `Shape` protocol.
+The `drawTwiceSome(_:)` function
+uses the type `some Shape` for its argument.
+This creates a new, unnamed generic type parameter for the function
+with a constraint that requires the type to conform to the `Shape` protocol.
+Because the generic type doesn't have a name,
+you can't refer to that type elsewhere in the function.
+
+If you write `some` before more than one parameter's type,
+each of the generic types are independent.
+For example:
+
+```swift
+func combine(shape s1: some Shape, with s2: some Shape) -> String {
+    return s1.draw() + "\n" + s2.draw()
+}
+
+combine(smallTriangle, trapezoid)
+```
+
+In the `combine(shape:with:)` function,
+the types of the first and second parameter
+must both conform to the `Shape` protocol,
+but there's no constraint that requires them to be the same type.
+When you call `combine(shape:with)`,
+you can pass two different shapes ---
+in this case, one triangle and one trapezoid.
+
+Unlike the syntax for named generic type parameters,
+described in <docc:Generics> chapter,
+this lightweight syntax can't include
+a generic `where` clause or any same-type (`==`) constraints.
+In addition,
+using the lightweight syntax for very complex constraints
+can be hard to read.
+
 <!--
 This source file is part of the Swift.org open source project
 

TSPL.docc/ReferenceManual/Types.md

@@ -864,7 +864,8 @@ that conforms to a protocol or protocol composition,
 without specifying the underlying concrete type.
 
 Opaque types appear as the return type of a function or subscript,
-or the type of a property.
+as the type of a parameter to a function, subscript, or initializer,
+or as the type of a property.
 Opaque types can't appear as part of a tuple type or a generic type,
 such as the element type of an array or the wrapped type of an optional.
 
@@ -909,6 +910,42 @@ that are part of the function's generic type parameters.
 For example, a function `someFunction<T>()`
 could return a value of type `T` or `Dictionary<String, T>`.
 
+Writing an opaque type for a parameter
+is syntactic sugar for using a generic type,
+without specifying a name for the generic type parameter.
+The implicit generic type parameter has a constraint
+that requires it to conform to the protocol named in the opaque type.
+If you write multiple opaque types,
+each one makes its own generic type parameter.
+For example, the following declarations are equivalent:
+
+```swift
+func someFunction(x: some MyProtocol, y: some MyProtocol) { }
+func someFunction<T1: MyProtocol, T2: MyProtocol>(x: T1, y: T2) { }
+```
+
+In the second declaration,
+because the generic type parameters `T1` and `T2` have names,
+you can refer use these types elsewhere in the code.
+In contrast,
+the generic type parameters in the first declaration
+don't have names and can't be referenced in other code.
+
+You can't use an opaque type in the type of a variadic parameter.
+
+You can't use an opaque type
+as a parameter to a function type being returned,
+or as a parameter in a parameter type that's a function type.
+In these positions,
+the function's caller would have to construct a value
+of that unknown type.
+
+```swift
+protocol MyProtocol { }
+func badFunction() -> (some MyProtocol) -> Void { }  // Error
+func anotherBadFunction(callback: (some MyProtocol) -> Void) { }  // Error
+```
+
 > Grammar of an opaque type:
 >
 > *opaque-type* → **`some`** *type*