improve docs

Author: xmnlab

docs/library/control-flow.md

@@ -0,0 +1,96 @@
+# Control Flow
+
+Arx currently supports `if`/`else`, `while`, and two `for` loop styles.
+
+## If / Else
+
+````arx
+```
+title: If/else example
+summary: Branches based on a comparison.
+```
+fn abs_value(x: i32) -> i32:
+  ```
+  title: abs_value
+  summary: Returns absolute value of x.
+  ```
+  if x < 0:
+    return 0 - x
+  else:
+    return x
+````
+
+## While Loop
+
+````arx
+```
+title: While loop example
+summary: Repeats while condition is true.
+```
+fn count_to_ten() -> i32:
+  ```
+  title: count_to_ten
+  summary: Increments value until it reaches ten.
+  ```
+  var a: i32 = 0
+  while a < 10:
+    a = a + 1
+  return a
+````
+
+## For Loop (Range Style)
+
+Range-style loops use the slice-like header:
+
+`for i in (start:end:step):`
+
+````arx
+```
+title: Range-style for loop
+summary: Iterates from start to end with step.
+```
+fn range_loop(n: i32) -> i32:
+  ```
+  title: range_loop
+  summary: Sums values produced by a range loop.
+  ```
+  var total: i32 = 0
+  for i in (0:n:1):
+    total = total + i
+  return total
+````
+
+Tuple-style range headers such as `(0, 5, 1)` are not supported.
+
+## For Loop (Count Style)
+
+Count-style loops follow:
+
+`for var i: type = init; condition; update:`
+
+````arx
+```
+title: Count-style for loop
+summary: Uses initializer, condition, and update expressions.
+```
+fn count_loop() -> i32:
+  ```
+  title: count_loop
+  summary: Sums numbers from 0 to 4.
+  ```
+  var total: i32 = 0
+  for var i: i32 = 0; i < 5; i = i + 1:
+    total = total + i
+  return total
+````
+
+## Return Statements
+
+- `return expr` returns a value from the current function.
+- `return none` is used for `none`-returning functions.
+
+## Indentation Rules
+
+- Blocks start after `:`.
+- The next logical line must be indented by one level (2 spaces in Arx style).
+- Misaligned indentation is treated as a parser error.

docs/library/datatypes.md

@@ -0,0 +1,112 @@
+# Data Types
+
+Arx uses explicit type annotations for variables, function parameters, and
+optional function return types.
+
+## Type Annotations
+
+- Function parameters must always be typed.
+- Function return type is optional. If omitted, current parser default is `f32`.
+- Variable declarations can include an explicit type with `var name: type`.
+
+````arx
+```
+title: Typed function signature
+summary: Demonstrates required parameter annotations.
+```
+fn add(a: i32, b: i32) -> i32:
+  ```
+  title: add
+  summary: Returns a + b.
+  ```
+  return a + b
+````
+
+## Built-in Types
+
+| Type        | Meaning                    | Example               |
+| ----------- | -------------------------- | --------------------- |
+| `i8`        | 8-bit integer              | `var a: i8 = 8`       |
+| `i16`       | 16-bit integer             | `var b: i16 = 16`     |
+| `i32`       | 32-bit integer             | `var c: i32 = 32`     |
+| `i64`       | 64-bit integer             | `var d: i64 = 64`     |
+| `f16`       | 16-bit float               | `var x: f16 = 1.5`    |
+| `f32`       | 32-bit float               | `var y: f32 = 3.25`   |
+| `bool`      | Boolean                    | `var ok: bool = true` |
+| `none`      | No value                   | `var n: none = none`  |
+| `str`       | String                     | `var s: str = "hi"`   |
+| `char`      | Character (mapped to `i8`) | `var ch: char = 'A'`  |
+| `datetime`  | Date/time literal          | `datetime("...")`     |
+| `timestamp` | Timestamp literal          | `timestamp("...")`    |
+| `list[T]`   | List type                  | `list[i32]`           |
+
+## Strings And Characters
+
+````arx
+```
+title: String and char types
+summary: Declares string and char variables.
+```
+fn text_demo() -> none:
+  ```
+  title: text_demo
+  summary: Uses string and char literals.
+  ```
+  var greeting: str = "hello"
+  var initial: char = 'A'
+  return none
+````
+
+## Date And Time Literals
+
+````arx
+```
+title: Datetime and timestamp literals
+summary: Creates date/time values from string literals.
+```
+fn time_demo() -> none:
+  ```
+  title: time_demo
+  summary: Demonstrates datetime/timestamp constructors.
+  ```
+  var dt: datetime = datetime("2026-03-05T12:30:59")
+  var ts: timestamp = timestamp("2026-03-05T12:30:59.123456789")
+  return none
+````
+
+## Lists
+
+````arx
+```
+title: List type example
+summary: Declares list variables.
+```
+fn list_demo() -> none:
+  ```
+  title: list_demo
+  summary: Declares populated and empty lists.
+  ```
+  var ids: list[i32] = [1, 2, 3, 4]
+  var empty_ids: list[i32] = []
+  return none
+````
+
+Current limitation: list code generation is still limited to empty or
+homogeneous integer constant lists.
+
+## Casting
+
+Use the built-in `cast(value, type)` to convert values:
+
+````arx
+```
+title: Casting example
+summary: Converts between numeric and string-compatible forms.
+```
+fn cast_demo(a: i32) -> str:
+  ```
+  title: cast_demo
+  summary: Returns string representation of an integer.
+  ```
+  return cast(a, str)
+````

docs/library/index.md

@@ -9,6 +9,8 @@ Start here when you need exact syntax and placement rules.
 
 - [Modules](modules.md)
 - [Functions](functions.md)
+- [Data Types](datatypes.md)
+- [Control Flow](control-flow.md)
 - [Docstrings](docstrings.md)
 
 ## Scope (Current Prototype)
@@ -17,6 +19,8 @@ This reference currently focuses on:
 
 - module structure
 - function definitions and calls
+- type system and annotations
+- control-flow syntax
 - docstring placement rules
 
 More feature pages can be added here as the language grows.

mkdocs.yaml

@@ -11,6 +11,8 @@ nav:
       - Overview: library/index.md
       - Modules: library/modules.md
       - Functions: library/functions.md
+      - Data Types: library/datatypes.md
+      - Control Flow: library/control-flow.md
       - Docstrings: library/docstrings.md
   - API Docs: api/
   - Sponsor: sponsor.md