Embiggen text font, add move and out arguments

And code block cleanup:
- highlight key lines in all code blocks
- remove redundant "Example:" in code block titles
- add a chained comparisons example

Author: hsutter

docs/cpp2/common.md

@@ -13,7 +13,7 @@ As always, `main` is the entry point of the program. For example:
     - 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` additionally provide access to the raw C/C++ `main` parameters.
 
-``` cpp title="Examples: main with (args)"
+``` cpp title="main with (args)" hl_lines="5 9"
 //  Print out command line arguments, then invoke
 //  a Qt event loop for a non-UI Qt application
 main: (args) -> int
@@ -40,7 +40,7 @@ main: (args) -> int
 
 The usual `// line comments` and `/* stream comments */` are supported. For example:
 
-``` cpp title="Example: Comments"
+``` cpp title="Writing comments"
 //  A line comment: After //, the entire
 //  rest of the line is part of the comment
 
@@ -98,7 +98,7 @@ Cpp2 supports the same fundamental types as today's Cpp1, but additionally provi
 
 Types can be qualified with `const` and `*`. Types are written left-to-right, so a qualifier always applies to what immediately follows it. For example, to declare a `const` pointer to a non-`const` pointer to a `const i32` object, write:
 
-``` cpp title="Example: Type qualifiers"
+``` cpp title="Using type qualifiers"
 //  A const pointer to a non-const pointer to a const i32 object
 p: const * * const i32;
 ```
@@ -123,7 +123,7 @@ Operators have the same precedence and associativity as in Cpp1, but some unary
 
 The operators `!`, `+`, and `-` are prefix, as in Cpp1. For example:
 
-``` cpp title="Example: Prefix operators"
+``` cpp title="Using prefix operators"
 if !vec.empty() {
     vec.emplace_back( -123.45 );
 }
@@ -137,7 +137,7 @@ if !vec.empty() {
 
 The operators `.`, `*`, `&`, `~`, `++`, `--`, `()`, `[]`, and `$` are postfix. For example:
 
-``` cpp title="Example: Postfix operators"
+``` cpp title="Using postfix operators"
 //  Cpp1 examples, from cppfront's own source code:
 //      address = &(*tokens)[pos + num];
 //      is_void = *(*u)->identifier == "void";

docs/cpp2/declarations.md

@@ -15,7 +15,7 @@ All Cpp2 declarations are written as **"_name_ `:` _kind_ `=` _statement_"**.
 
 ## Examples
 
-``` cpp title="Example: Consistent declarations — name : kind = statement"
+``` cpp title="Consistent declarations — name : kind = statement" hl_lines="2 5 10 17 21 25 34 40"
 //  n is a namespace defined as the following scope
 n: namespace
 = {

docs/cpp2/expressions.md

@@ -5,7 +5,7 @@
 
 `_` is pronounced **"don't care"** and allowed as a wildcard in most contexts. For example:
 
-``` cpp title="Example: _ wildcard"
+``` cpp title="Using the _ wildcard" hl_lines="2 5 11"
 //  We don't care about the guard variable's name
 _ : std::lock_guard = mut;
 
@@ -22,7 +22,7 @@ return inspect v -> std::string {
 
 Cpp2 treats all function outputs (return values, and results produced via `inout` and `out` parameters) as important, and does not let them be silently discarded by default. To explicitly discard such a value, assign it to `_`. For example:
 
-``` cpp title="Example: Using _ for explicit discard"
+``` cpp title="Using _ for explicit discard" hl_lines="1 8"
 _ = vec.emplace_back(1,2,3);
     // "_ =" is required to explicitly discard emplace_back's
     // return value (which is non-void since C++17)
@@ -88,7 +88,7 @@ Here are some `is` queries with their Cpp1 equivalents. In this table, uppercase
 
 An `x as T` expression allows safe type casts. `x` must be an object or expression, and `T` must be a type. It supports both static and dynamic typing, including customization with support for the standard dynamically typed libraries `std::variant`, `std::optional`, and `std::any` provided in the box. For example:
 
-``` cpp title="Example: Using as"
+``` cpp title="Using as" hl_lines="4 6 14"
 main: () = {
     a: std::any = 0;                // a's type is now int, value 0
     test(a);                        // prints "zero"
@@ -130,19 +130,21 @@ An `inspect expr -> Type` expression allows pattern matching using `is`.
 
 For example:
 
-``` cpp title="Example: Using inspect"
+``` cpp title="Using inspect" hl_lines="6-13"
 //  A generic function that takes an argument 'x' of any type
 //  and inspects various things about `x`
 test: (x) = {
     forty_two := 42;
-    std::cout << inspect x -> std::string {
-        is 0           = "zero";            // == 0
-        is (forty_two) = "the answer";      // == 42
-        is int         = "integer";         // is type int (and not 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";
+    std::cout
+        << inspect x -> std::string {
+            is 0           = "zero";            // == 0
+            is (forty_two) = "the answer";      // == 42
+            is int         = "integer";         // is type int (and not 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

docs/cpp2/functions.md

@@ -7,31 +7,48 @@ TODO
 
 ## Calling functions: `f(x)` syntax, and `x.f()` UFCS syntax
 
-A function call like `f(x)` is a normal non-member function call. It will call non-member functions only.
+A function call like `f(x)` is a normal function call that will call non-member functions only, as usual in C++.
 
 A function call like `x.f()` is a unified function call syntax (aka UFCS) call. It will call a member function if one is available, and otherwise will call `f(x)`. Having UFCS is important for generic code that may want to call a member or a non-member function, whichever is available. It's also important to enable fluid programming styles and natural IDE autocompletion support.
 
+An operator notation call like `a + b` will call an overloaded operator function if one is available, as usual in C++.
+
 For example:
 
-``` cpp title="Example: Function calls"
+``` cpp title="Function calls" hl_lines="3 7 11 16 19 20"
+//  Generic function to log something
+//  This calls operator<< using operator notation
+log: (x) = clog << x;
+
 f: ( v : std::vector<widget> ) = {
-    //  This calls std::vector::size()
-    std::cout << v.size();
+    //  This calls log() with the result of std::vector::size()
+    log( v.size() );
 
-    //  This calls std::ssize(v), because v
-    //  doesn't have a .ssize member function
-    std::cout << v.ssize();
+    //  This calls log() with the result of std::ssize(v), because
+    //  v doesn't have a .ssize member function
+    log( v.ssize() );
 }
 
 //  Generic function to print "hello, ___!" for any printable type
 hello: (name) = {
-    //  Using the C standard library is arguably nicer with UFCS
     myfile := fopen("xyzzy.txt", "w");
-    myfile.fprintf( "Hello, (name)%!\n" );
+    //  Direct calls to C nonmember functions, using UFCS and safe
+    //  string interpolation (instead of type-unsafe format strings)
+    myfile.fprintf( "Hello, (name)$!\n" );
     myfile.fclose();
+    //  The C and C++ standard libraries are not only fully available,
+    //  but safer (and arguably nicer) when used from Cpp2 syntax code
 }
 ```
 
+To explicitly treat an object name passed as an argument as `move` or `out`, write that keyword before the variable name.
+
+- Explicit `move` is rarely needed. Every definite last use of a local variable will apply `move` by default. Writing `move` from an object before its definite last use means that later uses may see a moved-from state.
+
+- Explicit `out` is needed only when initializing a local variable separately from its declaration using a call to a function with an `out` parameter. For details, see [Guaranteed initialization](../cpp2/objects.md#Init).
+
+For example:
+
 
 ## Parameters
 
@@ -62,7 +79,7 @@ A function's outputs are its return values, and the "out" state of any `out` and
 
 Function outputs cannot be silently discarded. To explicitly discard a function output, assign it to `_`. For example:
 
-``` cpp title="Example: No silent discard"
+``` cpp title="No silent discard" hl_lines="10 11 22 27"
 f: ()             -> void = { }
 g: ()             -> int  = { return 10; }
 h: (inout x: int) -> void = { x = 20; }
@@ -84,7 +101,7 @@ main: ()
     {
         x := 0;
         h( x );             // ok, x is referred to again...
-        _ = x;              // ... here, its value explicitly discarded
+        _ = x;              // ... here where its value explicitly discarded
     }
 
     {
@@ -114,7 +131,7 @@ TODO
 
 Loops can be named using the usual **name `:`** name introduction syntax, and `break` and `continue` can refer to those names. For example:
 
-``` cpp title="Example: Writing a simple type"
+``` cpp title="Using named break and continue" hl_lines="6 10"
 outer: while i<M next i++ {      // loop named "outer"
     // ...
     inner: while j<N next j++ {  // loop named "inner"

docs/cpp2/metafunctions.md

@@ -15,7 +15,7 @@ The most important thing about metafunctions is that they are not hardwired lang
 
 Metafunctions provide an easy way for a type author to opt into a group of defaults, constraints, and generated functions: Just write `@name` afer the `:` of a declaration, where `name` is the name of the metafunctions. This lets the type author declare (and the human reader see) the intent up front: "This isn't just any `type`, this is a `@value type`" which automatically gives the type default/copy/move construction and assignment, `<=>` with `std::strong_ordering` comparisons, and guarantees that it has a public destructor and no protected or virtual functions:
 
-``` cpp title="Example: Using the value metafunction when writing a type"
+``` cpp title="Using the value metafunction when writing a type" hl_lines="1"
 point2d: @value type = {
     x: i32 = 0;
     y: i32 = 0;
@@ -69,7 +69,7 @@ TODO
 
 Cpp2 has no `enum` feature hardwired into the language. Instead you apply the `@enum` metafunction when writing an ordinary `type`:
 
-``` cpp title="Example: Using @enum"
+``` cpp title="Using the @enum metafunction when writing a type" hl_lines="14"
 // skat_game is declaratively a safe enumeration type: it has
 // default/copy/move construction/assignment and <=> with
 // std::strong_ordering, a minimal-size signed underlying type
@@ -99,7 +99,7 @@ Unlike C `enum`, this `@enum` is scoped and strongly typed (does not implicitly
 
 Unlike C++11 `enum class`, it's "just a `type`" which means it can naturally also have member functions and other things that a type can have:
 
-``` cpp title="Example: An @enum type with a member function"
+``` cpp title="An @enum type with a member function" hl_lines="1"
 janus: @enum type = {
     past;
     future;
@@ -113,7 +113,7 @@ janus: @enum type = {
 
 There's also a `flag_enum` variation with power-of-two semantics and an unsigned underlying type:
 
-``` cpp title="Example: Using @flag_enum"
+``` cpp title="Using the @flag_enum metafunction when writing a type" hl_lines="11"
 // file_attributes is declaratively a safe flag enum type:
 // same as enum, but with a minimal-size unsigned underlying
 // type by default, and values that automatically start at 1
@@ -137,7 +137,7 @@ file_attributes: @flag_enum<u8> type = {
 
 `@union` declaratively opts into writing a safe discriminated union/variant dynamic type. For example:
 
-``` cpp title="Example: Using @union"
+``` cpp title="Using the @union metafunction when writing a type" hl_lines="9"
 // name_or_number is declaratively a safe union/variant type:
 // it has a discriminant that enforces only one alternative
 // can be active at a time, members always have a name, and
@@ -173,7 +173,7 @@ Each `@union` type has its own type-safe name, has clear and unambiguous named m
 
 Because a `@union type` is still a `type`, it can naturally have other things normal types can have, such as template parameter lists and member functions:
 
-``` cpp title="Example: A templated custom safe union type"
+``` cpp title="A templated custom safe union type" hl_lines="1"
 name_or_other: @union <T:type> type
 = {
     name  : std::string;

docs/cpp2/objects.md

@@ -13,7 +13,7 @@ Its declaration is written using the same **name `:` kind `=` value** [declarati
 
 For example:
 
-``` cpp title="Example: Declaring some objects"
+``` cpp title="Declaring some objects"
 //  numbers is an object of type std::vector<point2d>,
 //  defined as having the initial contents 1, 2, 3
 numbers: std::vector<int> = (1, 2, 3);
@@ -26,13 +26,13 @@ count := -1;        // same, deducing the object's type by just omitting it
 ```
 
 
-## Guaranteed initialization
+## <a id="Init"></a> Guaranteed initialization
 
 Every object must be initialized using `=` before it is used.
 
 An object in any scope can be initialized at its declaration. For example:
 
-``` cpp title="Example: Initializing objects when they are declared" hl_lines="4 10"
+``` cpp title="Initializing objects when they are declared" hl_lines="4 10"
 shape: type = {
     //  An object at type scope (data member)
     //  initialized with its type's default value
@@ -61,7 +61,7 @@ Additionally, at function local scope an object `obj` can be initialized separat
 
 For example:
 
-``` cpp title="Example: Initializing local objects after they are declared"
+``` cpp title="Initializing local objects after they are declared" hl_lines="5 14 17 21"
 f: () = {
     buf: std::array<std::byte, 1024>;   // uninitialized
     //  ... calculate some things ...
@@ -108,7 +108,7 @@ The default is `unique.new` if you don't specify an arena object.
 For example (see [types](types.md) for more details about writing types):
 
 
-``` cpp title="Example: Heap allocation"
+``` cpp title="Heap allocation" hl_lines="3-6 10-11"
 f: () -> std::shared_ptr<widget>
 = {
     //  Dynamically allocate an object owned by a std::unique_ptr

docs/cpp2/types.md

@@ -7,7 +7,7 @@ A user-defined `type` is written using the same **name `:` kind `=` value** [dec
 
 In a `type`, data members are private by default, and functions and nested types are public by default. To explicitly declare a type scope declaration `public`, `protected`, or `private`, write that keyword at the beginning of the declaration.
 
-``` cpp title="Example: Writing a simple type"
+``` cpp title="Writing a simple type" hl_lines="1"
 mytype: type =
 {
     // data members are private by default
@@ -40,7 +40,7 @@ The name `this` may only be used for the first parameter of a type-scope functio
 
 For example, here is how to write read-only member function named `print` that takes a read-only string value and prints this object's data value and the string message:
 
-``` cpp title="Example: this"
+``` cpp title="The this parameter" hl_lines="4 6"
 mytype: type = {
     data: i32;   // some data member (private by default)
 
@@ -73,11 +73,11 @@ A `this` parameter can additionally be declared as one of the following:
 
 - **`final`**: Writing `myfunc: (final this /*...*/)` defines a final override of an existing base class virtual function.
 
-A pure virtual function is a function with a `virtual this` parameter and no body.
+A pure virtual function is a function with a `virtual this` or `override this` parameter and no body.
 
 For example:
 
-``` cpp title="Example: Virtual functions"
+``` cpp title="Virtual functions" hl_lines="3 4 14 15"
 abstract_base: type
 = {
     //  A pure virtual function: virtual + no body
@@ -187,7 +187,7 @@ All copy/move/comparison `operator=` functions are memberwise by default in Cpp2
 
 For example:
 
-``` cpp title="Memberwise operator= semantics
+``` cpp title="Memberwise operator= semantics" hl_lines="9-11 20-22"
 mytype: type
 = {
     //  data members (private by default)
@@ -242,5 +242,12 @@ Most of Cpp2's `operator<=>` has already been merged into ISO C++, except for al
 
 - **Invalid chains: Everything else.** Nonsense chains like `a >= b < c` and `a != b != c` are compile time errors. They are "nonsense" because they are non-transitive; these chains do not imply any relationship between `a` and `c`.
 
+``` cpp title="Chained comparisons" hl_lines="2"
+//  If requested is in the range of values [lo, hi)
+if lo <= requested < hi {
+    // ... do something ...
+}
+```
+
 For details, see [P0515 "Consistent comparison" section 3.3](https://wg21.link/p0515) and [P0893 "Chaining comparisons"](https://wg21.link/p0893).
 

docs/stylesheets/extra.css

@@ -1,3 +1,9 @@
+/*
+    the default font sizes look small and encourage zooming,
+    which loses the navigation side panels
+*/
+p { font-size: 16px; }
+td { font-size: 16px; }
 
 /*
     todo: try to make the nav pane section labels larger
@@ -6,4 +12,4 @@
     to section starts are easier to see
 */
 .md-nav__item { font-size: 20pt; }
-.md-nav__link { font-size: medium; }
+.md-nav__link { font-size: medium; }

mkdocs.yml

@@ -58,10 +58,10 @@ nav:
     - 'Common expressions': cpp2/expressions.md
     - 'Declaration syntax': cpp2/declarations.md
     - 'Objects, initialization, and memory': cpp2/objects.md
-    - 'Functions': cpp2/functions.md
-    - 'Contracts': cpp2/contracts.md
-    - 'Types': cpp2/types.md
-    - 'Metafunctions & reflection API': cpp2/metafunctions.md
+    - 'Functions, branches, and loops': cpp2/functions.md
+    - 'Contracts and assertions': cpp2/contracts.md
+    - 'Types and inheritance': cpp2/types.md
+    - 'Metafunctions and reflection': cpp2/metafunctions.md
     - 'Namespaces': cpp2/namespaces.md
     - 'Aliases': cpp2/aliases.md
     - 'Modules': cpp2/modules.md