docs: update code examples and reference documentation for clarity and new features

Revise the code examples section to reflect changes in memory management and unsafe operations, including new examples for type aliases and destructors. Update the reference documentation to include type aliases in the design principles and lexical structure sections, enhancing clarity and usability. Remove the obsolete primitive types documentation and adjust related references accordingly.

Author: bialger

docs/reference/README.md

@@ -19,7 +19,6 @@ This page contains the Ovum language reference.
 
 ## Type system
 
-* [Primitive types](./primitive_types.md)
 * [Object model](./object_model.md)
 * [Nullable types](./nullable.md)
 

docs/reference/code_examples.md

@@ -182,7 +182,7 @@ fun DemoControlFlow(): Void {
 }
 ```
 
-## 9) Memory Management and Unsafe Operations
+## 9) Unsafe Operations
 
 ```ovum
 fun DemoUnsafeOperations(): Void {
@@ -209,7 +209,74 @@ fun DemoUnsafeOperations(): Void {
 }
 ```
 
-## 10) Complete Program Example
+## 10) Type Aliases
+
+```ovum
+// Define type aliases for better readability
+typealias UserId = Int
+typealias UserName = String
+typealias UserList = ObjectArray
+
+class User {
+    public val Id: UserId
+    public val Name: UserName
+    
+    public fun User(id: UserId, name: UserName): User {
+        this.Id = id
+        this.Name = name
+        return this
+    }
+}
+
+fun ProcessUsers(users: UserList): Void {
+    for (i in 0..users.Length()) {
+        val user: User = (users[i] as User)!!
+        sys::Print("User " + user.Id.ToString() + ": " + user.Name)
+    }
+}
+```
+
+
+## 11) Memory Management and Destructors
+
+```ovum
+class DatabaseConnection {
+    private val ConnectionId: Int
+    private val IsConnected: Bool
+    
+    public fun DatabaseConnection(id: Int): DatabaseConnection {
+        this.ConnectionId = id
+        this.IsConnected = true
+        // Establish database connection
+        return this
+    }
+    
+    public fun Query(sql: String): String {
+        if (!IsConnected) return "Not connected"
+        // Execute query
+        return "Query result"
+    }
+    
+    // Destructor called automatically by GC
+    public destructor(): Void {
+        if (IsConnected) {
+            // Close database connection
+            sys::Print("Closing connection " + ConnectionId.ToString())
+        }
+    }
+}
+
+fun DemoMemoryManagement(): Void {
+    val db: DatabaseConnection = DatabaseConnection(1)
+    val result: String = db.Query("SELECT * FROM users")
+    sys::Print("Query result: " + result)
+    
+    // db will be garbage collected automatically
+    // destructor will be called by GC
+}
+```
+
+## 12) Complete Program Example
 
 ```ovum
 // Complete Ovum program demonstrating key features
@@ -254,4 +321,4 @@ fun Main(args: StringArray): Int {
     
     return 0
 }
-```
+```

docs/reference/design.md

@@ -28,6 +28,8 @@ Ovum's core design principles center around:
   * **Access modifiers are mandatory** for all fields and methods in classes (`public`/`private`).
   * **Fields use `val` (immutable) or `var` (mutable)**.
 * **Namespaces** with `::` resolution (e.g., `sys::Print`).
+* **Functional objects** (`call` member) for functional programming.
+* **Type aliases** (`typealias` keyword) for better readability.
 * **Built-in operators**; **no user-defined operators**.
 * **Preprocessor**: `#import`, `#define`, `#ifdef`, `#ifndef`, `#else`, `#undef`.
 * **Managed runtime**: VM with **JIT** and **GC**; **no manual memory management**.

docs/reference/lexical_structure.md

@@ -10,7 +10,7 @@ Names for variables, functions, classes, etc., consist of letters, digits, and u
 
 ## Keywords
 
-Ovum reserves certain words like `fun`, `class`, `interface`, `var`, `override`, `pure`, `if`, `else`, `for`, `while`, `return`, `unsafe`, `val`, `static`, `public`, `private`, `implements`, `as`, `is`, `null`, `true`, `false`, etc. These cannot be used as identifiers.
+Ovum reserves certain words like `fun`, `class`, `interface`, `var`, `override`, `pure`, `if`, `else`, `for`, `while`, `return`, `unsafe`, `val`, `static`, `public`, `private`, `implements`, `as`, `is`, `null`, `true`, `false`, `typealias`, `destructor`, `call`, etc. These cannot be used as identifiers.
 
 ## Literals
 
@@ -54,7 +54,7 @@ Conditional     ::= "#ifdef" Identifier { GlobalDef | Import | Conditional }
                  | "#ifndef" Identifier { GlobalDef | Import | Conditional }
                     [ "#else" { GlobalDef | Import | Conditional } ] "#endif" ;
 
-GlobalDef       ::= FunctionDecl | ClassDecl | InterfaceDecl | GlobalVarDecl ;
+GlobalDef       ::= FunctionDecl | ClassDecl | InterfaceDecl | GlobalVarDecl | TypeAliasDecl ;
 
 FunctionDecl    ::= [ "pure" ] "fun" Identifier "(" [ ParamList ] ")" [ ":" Type ] Block ;
 ParamList       ::= Parameter { "," Parameter } ;
@@ -83,6 +83,8 @@ InterfaceCall   ::= "call" "(" [ ParamList ] ")" [ ":" Type ] ";" ;  // public &
 
 GlobalVarDecl   ::= [ "var" ] Identifier ":" Type "=" Expression ";" ;
 
+TypeAliasDecl   ::= "typealias" Identifier "=" Type ";" ;
+
 Type            ::= NullableType | NonNullType ;
 NullableType    ::= NonNullType "?" ;
 NonNullType     ::= PrimitiveType