From 2e120ce308b69aa9bbb101fac5e9c37bd532a148 Mon Sep 17 00:00:00 2001
From: Nick Treleaven <n@trelsoft.com>
Date: Tue, 21 Aug 2018 18:01:53 +0100
Subject: [PATCH 1/4] [spec] Document Ref and Out parameters properly

---
 spec/function.dd | 39 ++++++++++++++++++++++++++-------------
 1 file changed, 26 insertions(+), 13 deletions(-)

diff --git a/spec/function.dd b/spec/function.dd
index 231421b4ed..f490a23cb5 100644
--- a/spec/function.dd
+++ b/spec/function.dd
@@ -1238,10 +1238,10 @@ int foo(in int x, out int y, ref int z, int q);
     implemented so it's current implementation is equivalent to $(D const).  It is recommended
     to avoid using $(D in) until it is properly defined and implemented.  Use $(D scope const)
     or $(D const) explicitly instead.)
-    $(TROW $(D out), parameter is initialized upon function entry with the default value
+    $(TROW $(D ref), parameter is passed by reference)
+    $(TROW $(D out), parameter is passed by reference and initialized upon function entry with the default value
     for its type)
 
-    $(TROW $(D ref),   parameter is passed by reference)
     $(TROW $(D scope), references in the parameter
     cannot be escaped (e.g. assigned to a global variable).
     Ignored for parameters with no references)
@@ -1257,6 +1257,28 @@ int foo(in int x, out int y, ref int z, int q);
     $(TROW $(D inout), argument is implicitly converted to an inout type)
     )
 
+$(H3 $(LNAME2 ref-params, Ref and Out Parameters))
+
+    $(P By default, parameters take rvalue arguments.
+    A Ref parameter takes an lvalue argument, so changes to its value will operate
+    on the caller's argument.)
+
+$(SPEC_RUNNABLE_EXAMPLE_COMPILE
+---
+void def(ref int x)
+{
+    x += 1;
+}
+
+int z = 3;
+def(z);
+// z is now 4
+------------
+)
+
+    $(P An Out parameter `x` is similar to a Ref parameter, except it is initialized
+    with `x.init` upon function invocation.)
+
 $(SPEC_RUNNABLE_EXAMPLE_COMPILE
 ------
 void foo(out int x)
@@ -1277,19 +1299,10 @@ void abc(out int x)
 int y = 3;
 abc(y);
 // y is now 2
-
-void def(ref int x)
-{
-    x += 1;
-}
-
-int z = 3;
-def(z);
-// z is now 4
-------------
+---
 )
 
-        $(P For dynamic array and object parameters, which are passed
+        $(P For dynamic array and object parameters, which are always passed
         by reference, in/out/ref
         apply only to the reference and not the contents.
         )

From 2c2de734eeb0ee76a02e59304986ee6594c9971d Mon Sep 17 00:00:00 2001
From: Nick Treleaven <n@trelsoft.com>
Date: Thu, 23 Aug 2018 11:19:32 +0100
Subject: [PATCH 2/4] Use assert for examples

---
 spec/function.dd | 13 ++++++-------
 1 file changed, 6 insertions(+), 7 deletions(-)

diff --git a/spec/function.dd b/spec/function.dd
index f490a23cb5..4f93111682 100644
--- a/spec/function.dd
+++ b/spec/function.dd
@@ -1263,7 +1263,7 @@ $(H3 $(LNAME2 ref-params, Ref and Out Parameters))
     A Ref parameter takes an lvalue argument, so changes to its value will operate
     on the caller's argument.)
 
-$(SPEC_RUNNABLE_EXAMPLE_COMPILE
+$(SPEC_RUNNABLE_EXAMPLE_RUN
 ---
 void def(ref int x)
 {
@@ -1272,24 +1272,23 @@ void def(ref int x)
 
 int z = 3;
 def(z);
-// z is now 4
+assert(z == 4);
 ------------
 )
 
     $(P An Out parameter `x` is similar to a Ref parameter, except it is initialized
     with `x.init` upon function invocation.)
 
-$(SPEC_RUNNABLE_EXAMPLE_COMPILE
+$(SPEC_RUNNABLE_EXAMPLE_RUN
 ------
 void foo(out int x)
 {
-    // x is set to int.init,
-    // which is 0, at start of foo()
+    assert(x == 0);
 }
 
 int a = 3;
 foo(a);
-// a is now 0
+assert(x == 0);
 
 void abc(out int x)
 {
@@ -1298,7 +1297,7 @@ void abc(out int x)
 
 int y = 3;
 abc(y);
-// y is now 2
+assert(y == 2);
 ---
 )
 

From 112cdffa337c18ee2a28bce801f3e0bb4d90a3f5 Mon Sep 17 00:00:00 2001
From: Nick Treleaven <n@trelsoft.com>
Date: Thu, 23 Aug 2018 11:43:31 +0100
Subject: [PATCH 3/4] Add link to return ref parameters; fix case

---
 spec/function.dd | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/spec/function.dd b/spec/function.dd
index 4f93111682..a4271d8466 100644
--- a/spec/function.dd
+++ b/spec/function.dd
@@ -1260,7 +1260,7 @@ int foo(in int x, out int y, ref int z, int q);
 $(H3 $(LNAME2 ref-params, Ref and Out Parameters))
 
     $(P By default, parameters take rvalue arguments.
-    A Ref parameter takes an lvalue argument, so changes to its value will operate
+    A ref parameter takes an lvalue argument, so changes to its value will operate
     on the caller's argument.)
 
 $(SPEC_RUNNABLE_EXAMPLE_RUN
@@ -1275,8 +1275,10 @@ def(z);
 assert(z == 4);
 ------------
 )
+    $(P A ref parameter can also be returned by reference - see:
+    $(RELATIVE_LINK2 return-ref-parameters, $(D return ref) parameters.))
 
-    $(P An Out parameter `x` is similar to a Ref parameter, except it is initialized
+    $(P An out parameter `x` is similar to a ref parameter, except it is initialized
     with `x.init` upon function invocation.)
 
 $(SPEC_RUNNABLE_EXAMPLE_RUN

From 51257494ff4e9c7920dd6cd5d82b601b661eec0a Mon Sep 17 00:00:00 2001
From: Nick Treleaven <n@trelsoft.com>
Date: Tue, 16 Jun 2020 18:07:30 +0100
Subject: [PATCH 4/4] Fix assert; rename def -> inc

---
 spec/function.dd | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/spec/function.dd b/spec/function.dd
index a4271d8466..73b3d3d947 100644
--- a/spec/function.dd
+++ b/spec/function.dd
@@ -1265,13 +1265,13 @@ $(H3 $(LNAME2 ref-params, Ref and Out Parameters))
 
 $(SPEC_RUNNABLE_EXAMPLE_RUN
 ---
-void def(ref int x)
+void inc(ref int x)
 {
     x += 1;
 }
 
 int z = 3;
-def(z);
+inc(z);
 assert(z == 4);
 ------------
 )
@@ -1290,7 +1290,7 @@ void foo(out int x)
 
 int a = 3;
 foo(a);
-assert(x == 0);
+assert(a == 0);
 
 void abc(out int x)
 {