Function outputs and explicit discard

Author: hsutter

docs/cpp2/common.md

@@ -8,10 +8,10 @@ As always, `main` is the entry point of the program. For example:
 
 - No parameters: `main: () /*etc.*/`
 
-- One parameter of implicit type named `args`: `main: (args) /*etc*/`.
+- One parameter of implicit type named `args`: `main: (args) /*etc.*/`
     - The type of `args` cannot be explicitly specified. It is always `cpp2::args_t`, which behaves similarly to a `const std::array<std::string_view>`.
     - Using `args` performs zero heap allocations. Every `string_view` is directly bound to the string storage provided by host environment.
-    - `args.argc` and `args.argv` dditionally provide access to the raw C/C++ `main` parameters.
+    - `args.argc` and `args.argv` additionally provide access to the raw C/C++ `main` parameters.
 
 ``` cpp title="Examples: main with (args)"
 //  Print out command line arguments, then invoke

docs/cpp2/functions.md

@@ -25,12 +25,66 @@ f: ( v : std::vector<widget> ) = {
 }
 ```
 
+If the function has an output  that cannot be silently discarded, you can
 
-## Parameter passing
+
+## Parameters
+
+TODO
+
+> Note: All parameters and other objects in Cpp2 are `const` by default, except for local variables. For details, see [Design note: `const` objects by default](https://github.com/hsutter/cppfront/wiki/Design-note%3A-const-objects-by-default).
+
+
+## Return values
 
 TODO
 
-All parameters and other objects in Cpp2 are `const` by default, except for local variables. For details, see [Design note: `const` objects by default](https://github.com/hsutter/cppfront/wiki/Design-note%3A-const-objects-by-default).
+
+### Function outputs
+
+A function's outputs are its return values, and the "out" state of any `out` and `inout` parameters.
+
+Function outputs cannot be silently discarded. To explicitly discard a function output, assign it to `_`. For example:
+
+``` cpp title="Example: No silent discard"
+f: ()             -> void = { }
+g: ()             -> int  = { return 10; }
+h: (inout x: int) -> void = { x = 20; }
+
+main: ()
+= {
+    f();                    // ok, no return value
+
+    std::cout << g();       // ok, use return value
+    _ = g();                // ok, explicitly discard return value
+    g();                    // ERROR, return value is ignored
+
+    {
+        x := 0;
+        h( x );             // ok, x is referred to again...
+        std::cout << x;     // ... here, so its new value is used
+    }
+
+    {
+        x := 0;
+        h( x );             // ok, x is referred to again...
+        _ = x;              // ... here, its value explicitly discarded
+    }
+
+    {
+        x := 0;
+        h( x );             // ERROR, this is a definite last use of x
+    }                       // so x is not referred to again, and its
+                            // 'out' value can't be implicitly discarded
+}
+```
+
+> Cpp2 imbues Cpp1 code with nondiscardable semantics, while staying fully compatible as usual:
+>
+> - A function written in Cpp2 syntax that returns something other than `void` is always compiled to Cpp1 with `[[nodiscard]]`.
+>
+> - A function call written in Cpp2 `x.f()` member call syntax always treats a non-`void` return type as not discardable, even if the function was written in Cpp1 syntax that did not write `[[nodiscard]]`.
+
 
 ## Control flow
 

docs/cpp2/objects.md

@@ -45,8 +45,9 @@ f: () -> std::shared_ptr<widget>
     //  Dynamically allocate an object owned by a std::unique_ptr
     //  'vec' is a unique_ptr<vector<i32>> containing three values
     vec := new<std::vector<i32>>(1, 2, 3);
-        // shorthand for 'unique.new<...>(...)'
+            // shorthand for 'unique.new<...>(...)'
     std::cout << vec*.ssize();  // prints 3
+                    // note that * dereference is a suffix operator
 
     //  Dynamically allocate an object with shared ownership
     wid := cpp2::shared.new<widget>();