Merge pull request GaijinEntertainment#2081 from GaijinEntertainment/doc-cleanup

Doc cleanup

Author: borisbat

.github/copilot-instructions.md

@@ -48,13 +48,15 @@ All code examples and documentation MUST use gen2 syntax (add `options gen2` at
 - **Braces** on all blocks — no indentation-based blocks: `def foo() { ... }`, `if (x) { ... }`
 - **Construction:** `new Type(field=val)` — NOT `new [[Type() field=val]]`
 - **Enum access:** `EnumName.EnumValue` with dot — NOT `EnumName EnumValue` without
-- **Array literals:** `[1, 2, 3]` (commas, square brackets) — NOT `[[int 1; 2; 3]]`
+- **Array literals:** `[1, 2, 3]` (commas, square brackets) — NOT `[[int 1; 2; 3]]`. Note: this creates a **dynamic** `array<int>` — use `fixed_array(1, 2, 3)` for fixed-size arrays
 - **Struct init:** `Foo(a=1, b=2)` — NOT `[[Foo() a=1, b=2]]`
 - **No `[[ ]]` for `new`** — `new` always uses parentheses: `new Foo(x=1)`
 - **Table literals:** `{ "k" => v, "k2" => v2 }` (single braces, commas) — NOT `{{ "k" => v; "k2" => v2 }}`
 - **Named arguments:** `foo([name = value])` with square brackets — NOT `foo(name=value)`
 - **Block arguments with `<|`:** use `$()` or `@()` prefix: `defer() <| $() { ... }` — NOT `defer <| { ... }` (bare `{ }` creates a table literal)
 - **Lambda:** `@(args) { body }` or `@@(args) { body }` (no-capture)
+- **Generator:** `$() { yield value; }` or `$ { yield value; }` — both are valid gen2 syntax
+- **Tuple `=>` operator:** `a => b` creates a `tuple<auto;auto>` — useful in LINQ, table construction, and ad-hoc pairs
 - **Bitfield variables** need explicit type for `.field` access and printing: `var f : MyBitfield`
 - **Bitfield dot access:** read with `f.flag` (returns bool), write with `f.flag = true/false`
 - **`typeinfo`** special syntax: `typeinfo enum_length(type<MyEnum>)` — NOT `typeinfo(enum_length type<MyEnum>)`
@@ -110,6 +112,10 @@ All code examples and documentation MUST use gen2 syntax (add `options gen2` at
 - When calling `apply_template`, always capture the return value: `unsafe { expr <- apply_template(expr) <| ... }` — discarding the return loses the expression data
 - Iterator comprehension: `[iterator for(x in src); expression]` — semicolon separates generator from body
 - `to_array` (from `daslib/builtin`) converts any iterator to an array
+- Lambdas CAN be stored in arrays: `var fns : array<lambda<(x:int):int>>` + `fns |> emplace() <| @(x : int) : int { return x * 2; }` — move semantics, not copy
+- Blocks CANNOT be stored in containers, returned from functions, or captured — use lambdas or function pointers for those use cases
+- `match`, `multi_match`, `static_match` macros (from `daslib/match.das`) handle side effects automatically — do NOT add `[sideeffects]` annotations to functions that only use match
+- `[export] def main()` returns `void` — do NOT `return true` or return other values from main
 
 ## Key Directories
 
@@ -175,6 +181,45 @@ When editing RST files in `doc/source/reference/language/`:
 - Use `:ref:` cross-references to link between pages (labels: `_structs`, `_classes`, `_functions`, `_statements`, `_expressions`, `_arrays`, `_tables`, `_iterators`, `_generators`, `_lambdas`, `_blocks`, `_tuples`, `_variants`, `_bitfields`, `_aliases`, `_modules`, `_options`, `_unsafe`, `_enumerations`, `_generic_programming`, `_pattern-matching`, `_comprehensions`, `_string_builder`, `_macros`, `_reification`, `_finalizers`, `_clone`, `_temporary`, `_move_copy_clone`, `_annotations`, `_program_structure`, `_type_conversions`, `_contexts`, `_locks`, `_datatypes_and_values`)
 - Verify examples compile: `bin/Release/daslang.exe example.das`
 
+### RST table rules
+
+RST uses two table formats — **grid tables** and **simple tables**. Both are fragile:
+
+- **Grid tables** (`+---+---+`): Every row line must be exactly the same width as every separator line. Off-by-one spaces cause Sphinx errors.
+- **Simple tables** (`===  ===`): The `=` separator defines column widths. Content in non-last columns must NOT extend past its column's `=` boundary. Headers must start at or after the column's start position (not in the gap). The gap between columns must be at least 2 spaces.
+- After creating or editing any RST table, verify the file with a Sphinx build (see below).
+
+### Documentation workflow (REQUIRED)
+
+After creating or modifying any RST files, stdlib documentation, or `daslib/*.das` module doc-comments:
+
+1. **Regenerate stdlib docs** (if `daslib/*.das` files or `doc/reflections/das2rst.das` were changed):
+   ```
+   bin/Release/daslang.exe doc/reflections/das2rst.das
+   ```
+
+2. **Clean Sphinx build** — MUST delete cache; cached builds hide errors:
+   ```
+   cd doc
+   Remove-Item -Recurse -Force sphinx-build    # delete doctree cache
+   Remove-Item -Recurse -Force ../site/doc     # delete HTML output
+   sphinx-build -b html -d sphinx-build source ../site/doc
+   ```
+   On Linux/Mac:
+   ```
+   cd doc
+   rm -rf sphinx-build ../site/doc
+   sphinx-build -b html -d sphinx-build source ../site/doc
+   ```
+
+3. **Verify no new errors or warnings**: Check the build output for `ERROR` and `WARNING`. The build must introduce **no new** Sphinx errors or warnings compared to the baseline.
+
+**When to run the workflow:**
+- New or modified RST files (language docs, tutorials, stdlib docs)
+- New or modified `//!` doc-comments in `daslib/*.das` files
+- Changes to `doc/reflections/das2rst.das` or `doc/reflections/rst.das`
+- New public functions added to any `daslib/*.das` module (also update `group_by_regex` in `das2rst.das`)
+
 ### Tutorial RST conventions
 
 Tutorial RST files live in `doc/source/reference/tutorials/` with companion `.das` files in `tutorials/language/`.

CLAUDE.md

@@ -48,13 +48,15 @@ All code examples and documentation MUST use gen2 syntax (add `options gen2` at
 - **Braces** on all blocks — no indentation-based blocks: `def foo() { ... }`, `if (x) { ... }`
 - **Construction:** `new Type(field=val)` — NOT `new [[Type() field=val]]`
 - **Enum access:** `EnumName.EnumValue` with dot — NOT `EnumName EnumValue` without
-- **Array literals:** `[1, 2, 3]` (commas, square brackets) — NOT `[[int 1; 2; 3]]`
+- **Array literals:** `[1, 2, 3]` (commas, square brackets) — NOT `[[int 1; 2; 3]]`. Note: this creates a **dynamic** `array<int>` — use `fixed_array(1, 2, 3)` for fixed-size arrays
 - **Struct init:** `Foo(a=1, b=2)` — NOT `[[Foo() a=1, b=2]]`
 - **No `[[ ]]` for `new`** — `new` always uses parentheses: `new Foo(x=1)`
 - **Table literals:** `{ "k" => v, "k2" => v2 }` (single braces, commas) — NOT `{{ "k" => v; "k2" => v2 }}`
 - **Named arguments:** `foo([name = value])` with square brackets — NOT `foo(name=value)`
 - **Block arguments with `<|`:** use `$()` or `@()` prefix: `defer() <| $() { ... }` — NOT `defer <| { ... }` (bare `{ }` creates a table literal)
 - **Lambda:** `@(args) { body }` or `@@(args) { body }` (no-capture)
+- **Generator:** `$() { yield value; }` or `$ { yield value; }` — both are valid gen2 syntax
+- **Tuple `=>` operator:** `a => b` creates a `tuple<auto;auto>` — useful in LINQ, table construction, and ad-hoc pairs
 - **Bitfield variables** need explicit type for `.field` access and printing: `var f : MyBitfield`
 - **Bitfield dot access:** read with `f.flag` (returns bool), write with `f.flag = true/false`
 - **`typeinfo`** special syntax: `typeinfo enum_length(type<MyEnum>)` — NOT `typeinfo(enum_length type<MyEnum>)`
@@ -110,6 +112,10 @@ All code examples and documentation MUST use gen2 syntax (add `options gen2` at
 - When calling `apply_template`, always capture the return value: `unsafe { expr <- apply_template(expr) <| ... }` — discarding the return loses the expression data
 - Iterator comprehension: `[iterator for(x in src); expression]` — semicolon separates generator from body
 - `to_array` (from `daslib/builtin`) converts any iterator to an array
+- Lambdas CAN be stored in arrays: `var fns : array<lambda<(x:int):int>>` + `fns |> emplace() <| @(x : int) : int { return x * 2; }` — move semantics, not copy
+- Blocks CANNOT be stored in containers, returned from functions, or captured — use lambdas or function pointers for those use cases
+- `match`, `multi_match`, `static_match` macros (from `daslib/match.das`) handle side effects automatically — do NOT add `[sideeffects]` annotations to functions that only use match
+- `[export] def main()` returns `void` — do NOT `return true` or return other values from main
 
 ## Key Directories
 
@@ -175,6 +181,45 @@ When editing RST files in `doc/source/reference/language/`:
 - Use `:ref:` cross-references to link between pages (labels: `_structs`, `_classes`, `_functions`, `_statements`, `_expressions`, `_arrays`, `_tables`, `_iterators`, `_generators`, `_lambdas`, `_blocks`, `_tuples`, `_variants`, `_bitfields`, `_aliases`, `_modules`, `_options`, `_unsafe`, `_enumerations`, `_generic_programming`, `_pattern-matching`, `_comprehensions`, `_string_builder`, `_macros`, `_reification`, `_finalizers`, `_clone`, `_temporary`, `_move_copy_clone`, `_annotations`, `_program_structure`, `_type_conversions`, `_contexts`, `_locks`, `_datatypes_and_values`)
 - Verify examples compile: `bin/Release/daslang.exe example.das`
 
+### RST table rules
+
+RST uses two table formats — **grid tables** and **simple tables**. Both are fragile:
+
+- **Grid tables** (`+---+---+`): Every row line must be exactly the same width as every separator line. Off-by-one spaces cause Sphinx errors.
+- **Simple tables** (`===  ===`): The `=` separator defines column widths. Content in non-last columns must NOT extend past its column's `=` boundary. Headers must start at or after the column's start position (not in the gap). The gap between columns must be at least 2 spaces.
+- After creating or editing any RST table, verify the file with a Sphinx build (see below).
+
+### Documentation workflow (REQUIRED)
+
+After creating or modifying any RST files, stdlib documentation, or `daslib/*.das` module doc-comments:
+
+1. **Regenerate stdlib docs** (if `daslib/*.das` files or `doc/reflections/das2rst.das` were changed):
+   ```
+   bin/Release/daslang.exe doc/reflections/das2rst.das
+   ```
+
+2. **Clean Sphinx build** — MUST delete cache; cached builds hide errors:
+   ```
+   cd doc
+   Remove-Item -Recurse -Force sphinx-build    # delete doctree cache
+   Remove-Item -Recurse -Force ../site/doc     # delete HTML output
+   sphinx-build -b html -d sphinx-build source ../site/doc
+   ```
+   On Linux/Mac:
+   ```
+   cd doc
+   rm -rf sphinx-build ../site/doc
+   sphinx-build -b html -d sphinx-build source ../site/doc
+   ```
+
+3. **Verify no new errors or warnings**: Check the build output for `ERROR` and `WARNING`. The build must introduce **no new** Sphinx errors or warnings compared to the baseline.
+
+**When to run the workflow:**
+- New or modified RST files (language docs, tutorials, stdlib docs)
+- New or modified `//!` doc-comments in `daslib/*.das` files
+- Changes to `doc/reflections/das2rst.das` or `doc/reflections/rst.das`
+- New public functions added to any `daslib/*.das` module (also update `group_by_regex` in `das2rst.das`)
+
 ### Tutorial RST conventions
 
 Tutorial RST files live in `doc/source/reference/tutorials/` with companion `.das` files in `tutorials/language/`.

daslib/apply_in_context.das

@@ -29,11 +29,12 @@ class AppendCondAnnotation : AstFunctionAnnotation {
   //! If specified context is not installed, panic is called.
   //!
   //! For example::
-  //!  [apply_in_context(opengl_cache)]
-  //!  def public cache_font(name:string implicit) : Font?
-  //!      ...
-  //!  ...
-  //!  let font = cache_font("Arial") // call invoked in the "opengl_cache" debug agent context
+  //!
+  //!     [apply_in_context(opengl_cache)]
+  //!     def public cache_font(name:string implicit) : Font?
+  //!         ...
+  //!     ...
+  //!     let font = cache_font("Arial") // call invoked in the "opengl_cache" debug agent context
   def override patch(var func : FunctionPtr; var group : ModuleGroup; args, progArgs : AnnotationArgumentList; var errors : das_string; var astChanged : bool&) : bool {
 
     for (ann in func.annotations) {

daslib/array_boost.das

@@ -46,6 +46,7 @@ def private array_helper(arr : auto implicit ==const; a : auto(TT)) : array<TT -
 def public temp_array(var arr : auto implicit ==const) {
     //! Creates temporary array from the given object.
     //! Important requirements are:
+    //!
     //!     * object memory is linear
     //!     * each element follows the next one directly, with the stride equal to size of the element
     //!     * object memory does not change within the lifetime of the returned array
@@ -58,6 +59,7 @@ def public temp_array(var arr : auto implicit ==const) {
 def public temp_array(arr : auto implicit ==const) {
     //! Creates temporary array from the given object.
     //! Important requirements are:
+    //!
     //!     * object memory is linear
     //!     * each element follows the next one directly, with the stride equal to size of the element
     //!     * object memory does not change within the lifetime of the returned array
@@ -76,6 +78,7 @@ def empty(v : auto(VecT)) {
 def public temp_array(var data : auto? ==const; lenA : int; a : auto(TT)) : array<TT -const -#> {
     //! creates a temporary array from the given data pointer and length
     //! Important requirements are:
+    //!
     //!     * data pointer is valid and points to a memory block of at least lenA elements
     //!     * each element follows the next one directly, with the stride equal to size of the element
     //!     * data memory does not change within the lifetime of the returned array
@@ -92,6 +95,7 @@ def public temp_array(var data : auto? ==const; lenA : int; a : auto(TT)) : arra
 def public temp_array(data : auto? ==const; lenA : int; a : auto(TT)) : array<TT -const -#> const {
     //! creates a temporary array from the given data pointer and length
     //! Important requirements are:
+    //!
     //!     * data pointer is valid and points to a memory block of at least lenA elements
     //!     * each element follows the next one directly, with the stride equal to size of the element
     //!     * data memory does not change within the lifetime of the returned array

daslib/decs_boost.das

@@ -267,9 +267,11 @@ enum private DecsQueryType {
 
 [call_macro(name="query")]
 class DecsQueryMacro : AstCallMacro {
-    //! This macro implements 'query` functionality. There are 2 types of queries:
-    //!     * query(...) - returns a list of entities matching the query
-    //!     * query(eid) - returns a single entity matching the eid
+    //! This macro implements `query` functionality. There are 2 types of queries:
+    //!
+    //! * query(...) - returns a list of entities matching the query
+    //! * query(eid) - returns a single entity matching the eid
+    //!
     //! For example::
     //!
     //!     query() <| $ ( eid:EntityId; pos, vel : float3 )
@@ -280,6 +282,7 @@ class DecsQueryMacro : AstCallMacro {
     //!
     //!     query(kaboom) <| $ ( var pos:float3&; vel:float3; col:uint=13u )
     //!         pos += vel
+    //!
     //! The query above will add the velocity to the position of an entity with eid kaboom.
     //!
     //! Query can have `REQUIRE` and `REQUIRE_NOT` clauses::
@@ -302,7 +305,7 @@ class DecsQueryMacro : AstCallMacro {
     //!
     //! In the example above structure q : Particle does not exist as a variable. Instead it is expanded into accessing individual components of the entity.
     //! REQURE section of the query is automatically filled with all components of the template.
-    //! If template prefix is not specified, prefix is taken from the name of the template (would be "Particle_").
+    //! If template prefix is not specified, prefix is taken from the name of the template (would be ``Particle_``).
     //! Specifying empty prefix `[decs_template(prefix)]` will result in no prefix being added.
     //!
     //! Note: apart from tagging structure as a template, the macro also generates `apply_decs_template` and `remove_decs_template` functions.
@@ -477,10 +480,12 @@ class DecsQueryMacro : AstCallMacro {
 
 [call_macro(name="find_query")]
 class DecsFindQueryMacro : DecsQueryMacro {
-    //! This macro implements 'find_query` functionality.
+    //! This macro implements `find_query` functionality.
     //! It is similar to `query` in most ways, with the main differences being:
-    //!     * there is no eid-based find query
-    //!     * the find_query stops once the first match is found
+    //!
+    //! * there is no eid-based find query
+    //! * the find_query stops once the first match is found
+    //!
     //! For example::
     //!
     //!     let found = find_query <| $ ( pos,dim:float3; obstacle:Obstacle )
@@ -500,7 +505,7 @@ class DecsFindQueryMacro : DecsQueryMacro {
 
 [function_macro(name="decs")]
 class DecsEcsMacro : AstFunctionAnnotation {
-    //! This macro converts a function into a DECS pass stage query. Possible arguments are `stage`, 'REQUIRE', and `REQUIRE_NOT`.
+    //! This macro converts a function into a DECS pass stage query. Possible arguments are `stage`, `REQUIRE`, and `REQUIRE_NOT`.
     //! It has all other properties of a `query` (like ability to operate on templates). For example::
     //!
     //!     [decs(stage=update_ai, REQUIRE=ai_turret)]
@@ -587,12 +592,15 @@ class DecsEcsMacro : AstFunctionAnnotation {
 [call_macro(name="from_decs")]
 class FromDecsMacro : AstCallMacro {
     //! This macro converts a DECS query into an iterator<tuple<...>>. For example::
+    //!
     //!     let it = from_decs($(index:int; text:string){})
     //!     for (item in it) {
     //!         // process item
     //!         print("Entity {item.index}: {item.text}\n")
     //!     }
+    //!
     //! Internally it generates the following code::
+    //!
     //!     let it = invoke($() {
     //!         var res : array<tuple<int,string>>
     //!         query($(index:int; text:string) {

daslib/json_boost.das

@@ -214,12 +214,13 @@ class private BetterJsonMacro : AstVariantMacro {
 [reader_macro(name="json")]
 class private JsonReader : AstReaderMacro {
     //! This macro implements embedding of the JSON object into the program::
-    //!   var jsv = %json~
-    //!   {
-    //!     "name": "main_window",
-    //!     "value": 500,
-    //!     "size": [1,2,3]
-    //!   } %%
+    //!
+    //!     var jsv = %json~
+    //!     {
+    //!       "name": "main_window",
+    //!       "value": 500,
+    //!       "size": [1,2,3]
+    //!     } %%
     def override accept(prog : ProgramPtr; mod : Module?; var expr : ExprReader?; ch : int; info : LineInfo) : bool {
         //! Implement the accept method to read until '%%' is found.
         append(expr.sequence, ch)