From 9671946f026a463bab61694795f29918da0f60c1 Mon Sep 17 00:00:00 2001
From: Som Snytt <som.snytt@gmail.com>
Date: Tue, 27 Feb 2024 23:21:28 -0800
Subject: [PATCH] Tweak language for named args and example

---
 _tour/named-arguments.md | 26 +++++++++++++++++++-------
 1 file changed, 19 insertions(+), 7 deletions(-)

diff --git a/_tour/named-arguments.md b/_tour/named-arguments.md
index 911982e83..cec14a5eb 100644
--- a/_tour/named-arguments.md
+++ b/_tour/named-arguments.md
@@ -20,26 +20,38 @@ When calling methods, you can label the arguments with their parameter names lik
 {% tab 'Scala 2 and 3' for=named-arguments-when-good %}
 ```scala mdoc
 def printName(first: String, last: String): Unit =
-  println(first + " " + last)
+  println(s"$first $last")
 
-printName("John", "Smith")  // Prints "John Smith"
-printName(first = "John", last = "Smith")  // Prints "John Smith"
-printName(last = "Smith", first = "John")  // Prints "John Smith"
+printName("John", "Public")  // Prints "John Public"
+printName(first = "John", last = "Public")  // Prints "John Public"
+printName(last = "Public", first = "John")  // Prints "John Public"
+printName("Elton", last = "John")  // Prints "Elton John"
 ```
 {% endtab %}
 
 {% endtabs %}
 
-Notice how the order of named arguments can be rearranged. However, if some arguments are named and others are not, the unnamed arguments must come first and in the order of their parameters in the method signature.
+This is useful when two parameters have the same type and the arguments could be accidentally swapped.
+
+Notice that named arguments can be written in any order. However, once the arguments are not in parameter order, reading from left to right, then the rest of the arguments must be named.
+
+In the following example, named arguments enable the middle parameter to be omitted. But in the error case, the first argument is out of order, so the second argument must be named.
 
 {% tabs named-arguments-when-error %}
 
 {% tab 'Scala 2 and 3' for=named-arguments-when-error %}
 ```scala mdoc:fail
-printName(last = "Smith", "john") // error: positional after named argument
+def printFullName(first: String, middle: String = "Q.", last: String): Unit =
+  println(s"$first $middle $last")
+
+printFullName(first = "John", last = "Public")  // Prints "John Q. Public"
+printFullName("John", last = "Public")  // Prints "John Q. Public"
+printFullName("John", middle = "Quincy", "Public")  // Prints "John Quincy Public"
+printFullName(last = "Public", first = "John")  // Prints "John Q. Public"
+printFullName(last = "Public", "John")  // error: positional after named argument
 ```
 {% endtab %}
 
 {% endtabs %}
 
-Named arguments work with calls to Java methods, but only if the Java library in question was compiled with `-parameters`.
+Named arguments work with calls to Java methods, but only if the Java library in question was compiled with the `-parameters` flag.