From 6d7470ef132deda55dbcfbb81594f201367154df Mon Sep 17 00:00:00 2001
From: Bronley Plumb <bronley@gmail.com>
Date: Thu, 21 Jul 2022 09:15:44 -0400
Subject: [PATCH 1/3] Initial docs

---
 docs/named-arguments.md | 160 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 160 insertions(+)
 create mode 100644 docs/named-arguments.md

diff --git a/docs/named-arguments.md b/docs/named-arguments.md
new file mode 100644
index 000000000..e027ddd3b
--- /dev/null
+++ b/docs/named-arguments.md
@@ -0,0 +1,160 @@
+# Named arguments
+Named arguments allow you to match an argument to its position in the function parameter list by name.
+
+**NOTE:** Named arguments are not currently supported for function calls within complex expressions such as ternary, null coalescence, etc. This may change in the future as the compiler improves.
+
+## Simple usage
+For simple functions, the usage is straightforward. Simply prefix the value with the parmaeter name and a colon.
+```vb
+sub Greet(message as string, name as string)
+    print message + " " + name
+end sub
+
+sub main()
+    'normal call
+    Greet("Hello", "Alice")
+
+    'named argument call with params in same order
+    Greet(message: "Hello", name: "Brian")
+
+    'named argument call with params out of order
+    Greet(name: "Clarice", message: "Hello")
+end sub
+```
+
+transpiles to:
+
+```vb
+sub Greet(message as string, name as string)
+    print message + " " + name
+end sub
+
+sub main()
+    'normal call
+    Greet("Hello", "Alice")
+
+    'named argument call with params in same order
+    Greet("Hello", "Brian")
+
+    'named argument call with params out of order
+    Greet("Hello", "Clarice")
+end sub
+```
+
+## Named arguments after ordered parameters
+Named arguments can come after ordered parameters. Once named parameters are defined, all further parameters must also be named.
+
+In this example, notice how the first two params are ordered, while the rest are named:
+```vb
+sub main()
+    add(1, 2, four: 4, three: 3)
+end sub
+sub add(first, second, third, fourth)
+    return one + two + three + four
+end sub
+```
+
+transpiles to:
+```vb
+sub main()
+    'first two params are ordered, the rest are named
+    add(1, 2, 3, 4)
+end sub
+sub add(first, second, third, fourth)
+    return one + two + three + four
+end sub
+```
+
+## Optional parameters
+### Default values
+The BrightScript runtime is sensitive to type mismatches, we can't simply pass `invalid` for any unspecified optional named arguments. Instead, we need to lift the values out to the call site. For any unspecified optional parameters, the compiler looks at the default value of each argument and inlines them to the function call.
+
+Consider the following example:
+
+```vb
+sub main()
+    add(third: 75, first: 25)
+end sub
+
+sub add(first = 1 as integer, second = 2 as integer, third = 3 as integer)
+    return one + two + three
+end sub
+```
+
+transpiles to:
+
+```vb
+sub main()
+    add(25, 2, 75)
+end sub
+
+sub add(first = 1 as integer, second = 2 as integer, third = 3 as integer)
+    return one + two + three
+end sub
+```
+
+
+## Argument order matters
+With named arguments, the functions are called in the order they are defined. The compiler lifts any non-primitive values out of the function call to ensure the proper execution order is maintained.
+
+
+## Simple Use case
+```vb
+sub main()
+    BuildFullName(lastName: getLastName(), firstName: getFirstName())
+end sub
+
+function BuildFullName(firstName, lastName)
+    return firstName + " " + lastName
+end function
+```
+
+transpiles to:
+```vb
+sub main()
+    __bscNamedArg1_lastName = getLastName()
+    __bscNamedArg2_firstName = getLastName()
+    BuildFullName(__bscNamedArg2_firstName, __bscNamedArg1_lastName)
+end sub
+
+function BuildFullName(firstName, lastName)
+    return firstName + " " + lastName
+end function
+```
+
+### Complex use case
+```vb
+sub main()
+    print Concat(
+        text2: LCase("Alpha"),
+        text1: Concat(text2: LCase("Charlie"), text1: LCase("Beta"))
+    )
+end sub
+
+function concat(text1, text2)
+    return text1 + text2
+end function
+```
+
+transpiles to:
+
+```vb
+sub main()
+    __bscNamedArg1_text2 = LCase("Alpha")
+    __bscNamedArg2_text2 = LCase("Charlie")
+    __bscNamedArg3_text1 = LCase("Beta")
+
+    print Concat(
+        Concat(
+            __bscNamedArg3_text1,
+            __bscNamedArg2_text2
+        ),
+        __bscNamedArg1_text2
+    )
+end sub
+
+function concat(text1, text2)
+    return text1 + text2
+end function
+```
+

From 8f6776dcd288fa46792686c12322ca308e09548a Mon Sep 17 00:00:00 2001
From: Bronley Plumb <bronley@gmail.com>
Date: Thu, 21 Jul 2022 09:19:28 -0400
Subject: [PATCH 2/3] add limitations

---
 docs/named-arguments.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/docs/named-arguments.md b/docs/named-arguments.md
index e027ddd3b..a07ee3402 100644
--- a/docs/named-arguments.md
+++ b/docs/named-arguments.md
@@ -1,7 +1,9 @@
 # Named arguments
 Named arguments allow you to match an argument to its position in the function parameter list by name.
 
-**NOTE:** Named arguments are not currently supported for function calls within complex expressions such as ternary, null coalescence, etc. This may change in the future as the compiler improves.
+## Limitations
+ - is only supported for functions where bsc can clearly identify the function signature. (i.e. unsupported for object method calls, callfuncs, etc).
+ - named argument usage utilizing complex expressions many not be used for function calls within complex expressions such as ternary, null coalescence, etc. This may change in the future as the compiler improves.
 
 ## Simple usage
 For simple functions, the usage is straightforward. Simply prefix the value with the parmaeter name and a colon.

From ccd7bc49495799e17333b24f6bf6a268c0210bba Mon Sep 17 00:00:00 2001
From: Bronley Plumb <bronley@gmail.com>
Date: Thu, 21 Jul 2022 10:35:50 -0400
Subject: [PATCH 3/3] add namespace example

---
 docs/named-arguments.md | 34 ++++++++++++++++++++++++++++++----
 1 file changed, 30 insertions(+), 4 deletions(-)

diff --git a/docs/named-arguments.md b/docs/named-arguments.md
index a07ee3402..bc6537c12 100644
--- a/docs/named-arguments.md
+++ b/docs/named-arguments.md
@@ -27,10 +27,6 @@ end sub
 transpiles to:
 
 ```vb
-sub Greet(message as string, name as string)
-    print message + " " + name
-end sub
-
 sub main()
     'normal call
     Greet("Hello", "Alice")
@@ -41,6 +37,36 @@ sub main()
     'named argument call with params out of order
     Greet("Hello", "Clarice")
 end sub
+
+sub Greet(message as string, name as string)
+    print message + " " + name
+end sub
+```
+
+## Namespace functions
+Named arguments can be used for namespace function calls as well
+```vb
+sub main()
+   console.write(message: "Hello world", logLevel: "INFO")
+end sub
+
+namespace console
+    sub write(logLevel as string, message as string)
+        print logLevel + ": " + message
+    end sub
+end namespace
+```
+
+transpiles to:
+
+```vb
+sub main()
+   console_write("INFO", "Hello world")
+end sub
+
+sub console_write(logLevel as string, message as string)
+    print logLevel + ": " + message
+end sub
 ```
 
 ## Named arguments after ordered parameters