More details on named type arguments

Author: smarter

docs/docs/reference/named-typeargs-spec.md

@@ -0,0 +1,56 @@
+---
+layout: doc-page
+title: "Named Type Arguments - More Details"
+---
+
+## Syntax
+
+The addition to the grammar is:
+
+```
+SimpleExpr1       ::=  ...
+                    |  SimpleExpr (TypeArgs | NamedTypeArgs)
+NamedTypeArgs     ::=  ‘[’ NamedTypeArg {‘,’ NamedTypeArg} ‘]’
+NamedTypeArg      ::=  id ‘=’ Type
+```
+
+Note in particular that named arguments cannot be passed to type constructors:
+
+``` scala
+class C[T]
+
+val x: C[T = Int] = // error
+  new C[T = Int] // error
+
+class E extends C[T = Int] // error
+```
+
+## Multiple argument lists
+
+When arguments for some parameters are omitted, it's possible to specify the
+remaining arguments using another argument list:
+
+```scala
+def construct[Elem, Coll[_]](xs: Elem*): Coll[Elem] = ???
+
+construct[Coll = List][Elem = Int](1, 2, 3)
+construct[Coll = List][Int](1, 2, 3)
+```
+
+It's not possible to specify the same argument multiple times this way:
+
+```scala
+construct[Coll = List][Coll = List](1, 2, 3) // error
+```
+
+## Compatibility considerations
+
+Named type arguments do not have an impact on binary compatibility, but they
+have an impact on source compatibility: if the name of a method type parameter
+is changed, any existing named reference to this parameter will break. This
+means that the names of method type parameters are now part of the public API
+of a library.
+
+(Unimplemented proposal: to mitigate this,
+[`scala.deprecatedName`](https://www.scala-lang.org/api/current/scala/deprecatedName.html)
+could be extended to also be applicable on method type parameters.)

docs/docs/reference/named-typeargs.md

@@ -5,21 +5,24 @@ title: "Named Type Arguments"
 
 Type arguments of methods can now be named, as well as by position. Example:
 
+``` scala
+def construct[Elem, Coll[_]](xs: Elem*): Coll[Elem] = ???
 
-    def construct[Elem, Coll[_]](xs: Elem*): Coll[Elem] = ???
-
-    val xs2 = construct[Coll = List, Elem = Int](1, 2, 3)
-    val xs3 = construct[Coll = List](1, 2, 3)
+val xs1 = construct[Coll = List, Elem = Int](1, 2, 3)
+val xs2 = construct[Coll = List](1, 2, 3)
+```
 
 Similar to a named value argument `(x = e)`, a named type argument
 `[X = T]` instantiates the type parameter `X` to the type `T`. Type
 arguments must be all named or un-named, mixtures of named and
 positional type arguments are not supported.
 
-The main benefit of named type arguments is that they allow some
-arguments to be omitted. Indeed, if type arguments are named, some
-arguments may be left out.  An example is the definition of `xs3`
-above. A missing type argument is inferred as usual by local type
-inference. The same is not true for positional arguments, which must always
-be provided for all type parameters.
+## Motivation
+
+The main benefit of named type arguments is that unlike positional arguments,
+you are allowed to omit passing arguments for some parameters, like in the
+definition of `xs2` above. A missing type argument is inferred as usual by
+local type inference. This is particularly useful in situations where some type
+arguments can be easily inferred from others.
 
+[More details](./named-typeargs-spec.html)

tests/neg/namedTypeParams.scala

@@ -9,4 +9,8 @@ object Test {
   class E extends C[T = Int] // error: ']' expected, but `=` found // error
   class F extends C[T = Int]() // error: ']' expected, but `=` found // error
 
+  def f[X, Y](x: X, y: Y): Int = ???
+
+  f[X = Int, String](1, "") // error
+  f[X = Int][X = Int][Y = String](1, "") // error
 }

tests/pos/namedTypeParams.scala

@@ -6,4 +6,10 @@ object Test {
   f[X = Int, Y = String](1, "")
   f[X = Int](1, "")
   f[Y = String](1, "")
+
+  f[X = Int][Y = String](1, "")
+  f[X = Int][String](1, "")
+
+  f[Y = String][X = Int](1, "")
+  f[Y = String][Int](1, "")
 }