Document declarations, improve inspect discussion

Author: hsutter

docs/index.md

@@ -17,7 +17,7 @@ We can't make an improvement that large to C++ via gradual evolution to today's
 
 - **Freedom to make any desired improvement, without breaking any of today's code.** Cpp2 is designed to take all the consensus C++ best-practices guidance we already teach, and make it the default when using "syntax 2." Examples: Writing unsafe type casts is just not possible in Cpp2 syntax; and Cpp2 can change language defaults to make them simpler and safer. You can always "break the glass" when needed to violate the guidance, but has to opt out explicitly to write unsafe code, so if the program has a bug you can grep for those places to look at first. For details, see [Design note: unsafe code](https://github.com/hsutter/cppfront/wiki/Design-note%3A-Unsafe-code).
 
-- **Perfect link compatibility always on, perfect source compatibility always available (but you pay for it only if you use it).** Any type/function/object written in either syntax is always still just a normal C++ type/function/object, so any code or library written in either Cpp2 or today's C++ syntax ("Cpp1" for short) can seamlessly call each other, with no wrapping/marshaling/thunking. You can write a "mixed" source files that has both Cpp2 and Cpp1 code and get perfect backward C++ source compatibility (even SFINAE and macros), or you can write a "pure" all-Cpp2 source file and write code in a 10x simpler syntax.
+- **Perfect link compatibility always on, perfect source compatibility always available (but you pay for it only if you use it).** Any type/function/object/namespace/module/etc. written in either syntax is always still just a normal C++ type/function/object/namespace/module/etc., so any code or library written in either Cpp2 or today's C++ syntax ("Cpp1" for short) can seamlessly call each other, with no wrapping/marshaling/thunking. You can write a "mixed" source files that has both Cpp2 and Cpp1 code and get perfect backward C++ source compatibility (even SFINAE and macros), or you can write a "pure" all-Cpp2 source file and write code in a 10x simpler syntax.
 
 **What it isn't.** Cpp2 is not a successor or alternate language with it own divergent or incompatible ecosystem. For example, it does not have its own nonstandard incompatible modules/concepts/etc. that compete with the Standard C++ features; and does not replace your Standard C++ compiler and other tools.
 
@@ -79,7 +79,7 @@ hello: (msg: std::string_view) =
 
 This short program code already illustrates a few Cpp2 essentials.
 
-**Consistent context-free syntax.** Cpp2 is designed so that there is one general way to spell a given thing, that works consistently everywhere. All Cpp2 type/function/object declarations use the unambiguous and context-free syntax **"_name_ `:` _kind_ `=` _statement_"**. The `:` is pronounced **"is a,"** and the `=` is pronounced is pronounced **"defined as."**
+**Consistent context-free syntax.** Cpp2 is designed so that there is one general way to spell a given thing, that works consistently everywhere. All Cpp2 type/function/object/namespace/module/etc. declarations use the unambiguous and context-free syntax **"_name_ `:` _kind_ `=` _statement_"**. The `:` is pronounced **"is a,"** and the `=` is pronounced is pronounced **"defined as."**
 
 - `main` **is a** function that takes no arguments and returns nothing, and is **defined as** the code body shown.
 
@@ -236,7 +236,7 @@ That's enough to enable builds, and the IDE just picks up the rest from the `.cp
 
 - **The `#line` directives cppfront emits in the generated `.cpp` file.** Most C++ debuggers recognize these and will know to step through the `.cpp2` file. Note that `#line` emission is on by default, but if you choose `-c` (short for `-clean-cpp1`) these will be suppressed and then the debugger will step through the generated C++ code instead.
 
-- **Regardless of syntax, every type/function/object is still just an ordinary C++ type/function/object.** Most C++ debugger visualizers will just work and show beautiful output for the types your program uses, including to use any in-the-box visualizers for all the `std::` types (since those are used directly as usual) and any custom visualizers you may have already written for your own types or popular library types.
+- **Regardless of syntax, every type/function/object/namespace/module/etc. is still just an ordinary C++ type/function/object/namespace/module/etc.** Most C++ debugger visualizers will just work and show beautiful output for the types your program uses, including to use any in-the-box visualizers for all the `std::` types (since those are used directly as usual) and any custom visualizers you may have already written for your own types or popular library types.
 
 
 

docs/reference-cpp2.md

@@ -17,6 +17,60 @@ The usual `// line comments` and `/* stream comments */` are supported. For exma
  */
 ```
 
+### Declarations
+
+All Cpp2 declarations are written as **"_name_ `:` _kind_ `=` _statement_"**.
+
+- The `:` is pronounced **"is a."**
+- The `=` is pronounced is pronounced **"defined as."**
+- The _statement_ is typically an expression statement (e.g., `a + b();`) or a compound statement (e.g., `{ /*...*/ return c(d) / e; }`).
+
+For example:
+
+``` cpp title="Example: Consistent declartions — name : kind = statement"
+// n is a namespace defined as the following scope
+n: namespace
+= {
+    // shape is a type defined as the following scope
+    shape: type
+    = {
+        // points is an object of type std::vector<point2d>,
+        // defined as having an empty default value
+        // (type-scope objects are private by default)
+        points: std::vector<point2d> = ();
+
+        // draw is a function taking 'this' and 'canvas' parameters
+        // and returning bool, defined as the following body
+        // (type-scope functions are public by default)
+        //   - this is as if 'this: shape', an object of type shape
+        //   - where is an object of type canvas
+        draw: (this, where: canvas) -> bool
+        = {
+            // pen is an object of deduced (omitted) type 'color',
+            // defined as having initial value 'color::red'
+            pen := color::red;
+
+            // success is an object of deduced (omitted) type bool,
+            // defined as having initial value 'false'
+            success := false;
+
+            // ...
+
+            return success;
+        }
+
+        // count is a function taking 'this' and returning a type
+        // deduced from its body, defined as a single-expression body
+        count: (this) = points.ssize();
+
+        // ...
+    }
+
+    // color is an @enum type (described later)
+    color: @enum type = { red; green; blue; }
+}
+```
+
 ### The `_` wildcard, including explicit discard
 
 `_` is pronounced **"don't care"** and allowed as a wildcard in most contexts. For example:
@@ -237,9 +291,16 @@ test: (x) = {
 }
 ```
 
-### `inspect` expressions — pattern matching
+### `inspect` — pattern matching
+
+An `inspect expr -> Type` expression allows pattern matching using `is`.
 
-An `inspect` expression allows pattern matching using `is`. For example:
+- `expr` is evaluated once.
+- Each alternative spelled `is C` is evaluated in order as if called with `expr is C`.
+- If an alternative evaluates to `true`, then its `= alternative;` body is used as the value of the entire `inspect` expression, and the meaning is the same as if the entire `inspect` expression had been written as just `:Type = alternative;` — i.e., an unnamed object expression (aka 'temporary object') of type `Type` initialized with `alternative`.
+- A catchall `is _` is required.
+
+For example:
 
 ``` cpp title="Example: Using inspect"
 //  A generic function that takes an argument 'x' of any type
@@ -248,19 +309,25 @@ test: (x) = {
     forty_two := 42;
     std::cout << inspect x -> std::string {
         is 0           = "zero";            // == 0
-        is (forty_two) = "the answer";      // == forty_two
-        is int         = "integer";         // is an int with some other value
-        is std::string = x as std::string;  // is a std::string
-        is std::vector = "a std::vector";   // is a vector</*some-type*/>
-        is _           = "(no match)";      // something else
+        is (forty_two) = "the answer";      // == 42
+        is int         = "integer";         // is type int (value other than 0 or 42)
+        is std::string = x as std::string;  // is type std::string
+        is std::vector = "a std::vector";   // is a vector</*of-some-type*/>
+        is _           = "(no match)";      // is something else
     } << "\n";
 }
+
+//  Sample call site
+test(42);
+    //  Behaves as if the following function were called:
+    //      test: (x) = { std::cout << (:std::string = "the answer") << "\n";; }
+    //  (and that's why inspect alternatives are introduced with '=')
 ```
 
 For more examples, see also the examples in the previous two sections on `is` and `as`, many of which use `inspect`.
 
 
-### Captures, including interpolations
+### `$` — captures, including interpolations
 
 
 For details, see [Design note: Capture](https://github.com/hsutter/cppfront/wiki/Design-note%3A-Capture).