From acfa97f5277624db0afcb5c9749f0856a0f13fc6 Mon Sep 17 00:00:00 2001
From: Neil Henderson <2060747+bluetarpmedia@users.noreply.github.com>
Date: Tue, 27 Feb 2024 09:13:33 +1000
Subject: [PATCH 1/2] Update functions.md

Signed-off-by: Neil Henderson <2060747+bluetarpmedia@users.noreply.github.com>
---
 docs/cpp2/functions.md | 29 ++++++++++++++++++++++++++---
 1 file changed, 26 insertions(+), 3 deletions(-)

diff --git a/docs/cpp2/functions.md b/docs/cpp2/functions.md
index 61beac6a19..e9438ace64 100644
--- a/docs/cpp2/functions.md
+++ b/docs/cpp2/functions.md
@@ -3,7 +3,7 @@
 
 ## Overview
 
-A function is defined by writing a function signature after the `:` and a statement (expression or `{` `}` compound statement) after the `=`. After the optional [template parameters](declarations.md#template-parameters) available for all declarations, a function signatures consists of a possibly-empty [parameter list](#parameters), and an optional function [return values](#return-values).
+A function is defined by writing a function signature after the `:` and a statement (expression or `{` `}` compound statement) after the `=`. After the optional [template parameters](declarations.md#template-parameters) available for all declarations, a function signature consists of a possibly-empty [parameter list](#parameters), and one or more optional [return values](#return-values).
 
 For example, the minimal function named `func` that takes no parameters and returns nothing (`#!cpp void`) is:
 
@@ -14,7 +14,7 @@ func: ( /* no parameters */ ) = { /* empty body */ }
 
 ## <a id="parameters"></a> Parameters
 
-The parameter list is enclosed by `(` `)` parentheses, and the parameters separated by commas. Each parameter is declared using the [same syntax as any object](declarations.md). For example:
+The parameter list is enclosed by `(` `)` parentheses and the parameters are separated by commas. Each parameter is declared using the [same unified syntax](declarations.md) as used for all declarations. For example:
 
 ``` cpp title="Declaring parameters" hl_lines="2-4"
 func: (
@@ -67,7 +67,30 @@ add: (a, b) -> _ = a+b;
 
 (2) **`#!cpp -> ( /* parameter list */ )`** to return a list of named return parameters using the same [parameters](#parameters) syntax, but where the only passing styles are `out` (the default, which moves where possible) or `forward`. The function body must [initialize](objects.md#init) the value of each return-parameter `ret` in its body the same way as any other local variable. An explicit return statement is written just `#!cpp return;` and returns the named values; the function has an implicit `#!cpp return;` at the end. For example:
 
-``` cpp title="Functions with multiple/named return values" hl_lines="7 9 10 22-24"
+``` cpp title="Function with multiple/named return values" hl_lines="1 3-4 7-8 13-14 17-18"
+divide: (dividend: int, divisor: int) -> (quotient: int, remainder: int) = {
+    if divisor == 0 {
+        quotient = 0;
+        remainder = 0;
+    }
+    else {
+        quotient = dividend / divisor;
+        remainder = dividend % divisor;
+    }
+}
+
+main: () -> int = {
+    div:= divide(11, 5);
+    std::cout << div.quotient << ", " << div.remainder << "\n";
+    return 0;
+}
+//  Prints:
+//     2, 1
+```
+
+This next example declares a [member function](types.md#this-parameter) with multiple return values in a [type](types.md) named `set`:
+
+``` cpp title="Member function with multiple/named return values" hl_lines="7 9 10 22-24"
 set: <Key> type = {
     container: std::set<Key>;
     iterator : type == std::set<Key>::iterator;

From 0bc8d0715fe64109442fe2e757d7782def203681 Mon Sep 17 00:00:00 2001
From: Herb Sutter <herb.sutter@gmail.com>
Date: Mon, 26 Feb 2024 18:14:28 -0800
Subject: [PATCH 2/2] Tweak comments for divide example

---
 docs/cpp2/functions.md | 17 ++++++++---------
 1 file changed, 8 insertions(+), 9 deletions(-)

diff --git a/docs/cpp2/functions.md b/docs/cpp2/functions.md
index e9438ace64..6b1b6090b1 100644
--- a/docs/cpp2/functions.md
+++ b/docs/cpp2/functions.md
@@ -67,22 +67,21 @@ add: (a, b) -> _ = a+b;
 
 (2) **`#!cpp -> ( /* parameter list */ )`** to return a list of named return parameters using the same [parameters](#parameters) syntax, but where the only passing styles are `out` (the default, which moves where possible) or `forward`. The function body must [initialize](objects.md#init) the value of each return-parameter `ret` in its body the same way as any other local variable. An explicit return statement is written just `#!cpp return;` and returns the named values; the function has an implicit `#!cpp return;` at the end. For example:
 
-``` cpp title="Function with multiple/named return values" hl_lines="1 3-4 7-8 13-14 17-18"
+``` cpp title="Function with multiple/named return values" hl_lines="1 3-4 7-8 14 16-17"
 divide: (dividend: int, divisor: int) -> (quotient: int, remainder: int) = {
     if divisor == 0 {
-        quotient = 0;
-        remainder = 0;
+        quotient  = 0;                      // constructs quotient
+        remainder = 0;                      // constructs remainder
     }
     else {
-        quotient = dividend / divisor;
-        remainder = dividend % divisor;
+        quotient = dividend / divisor;      // constructs quotient
+        remainder = dividend % divisor;     // constructs remainder
     }
 }
 
-main: () -> int = {
-    div:= divide(11, 5);
-    std::cout << div.quotient << ", " << div.remainder << "\n";
-    return 0;
+main: () = {
+    div := divide(11, 5);
+    std::cout << "(div.quotient)$, (div.remainder)$\n";
 }
 //  Prints:
 //     2, 1