Document statements.

docs/Features/Standard-Library/File-IO.md

@@ -11,7 +11,7 @@ The `Open` statement supports Unicode through the use of a new `Encoding` keywor
 ## Usage Example
 
 ```tb
-Open "C:\MyFile.txt" For Input Encoding utf-8 As #1
+Open "C:\MyFile.txt" For Input Encoding utf_8 As #1
 ```
 
 ## Supported Encodings

docs/Reference/Categories.md

@@ -16,13 +16,16 @@ This chapter lists the global statements and procedures that form the core of th
 
 * [Option](../tB/Core/Option) - configure a compiler option
 * [#If ... Then ... Else](../tB/Core/Topic-Preprocessor) - enable or disable compilation of enclosed code
+* [#Const](../tB/Core/Topic-Preprocessor) - define a module-private conditional compiler constant
 
 ## Declarations and Definitions
 
 * [Class](../tB/Core/Class), [Module](../tB/Core/Module) - define a class or module
+* [Interface](../tB/Core/Interface), [CoClass](../tB/Core/CoClass) - (twinBASIC) define a COM interface or coclass using twinBASIC syntax
 * [Sub](../tB/Core/Sub) - define a procedure
 * [Function](../tB/Core/Function) - define a function
 * [Property](../tB/Core/Property) - define a property
+* [ParamArray](../tB/Core/ParamArray) - declare a procedure's final parameter as a variadic argument list
 * [Enum](../tB/Core/Enum) - define an enumeration type with associated constants
 * [Type](../tB/Core/Type) - declare a user-defined data type (UDT)/a structure
 * [Declare](../tB/Core/Declare) - declare an external/library procedure or function
@@ -39,6 +42,7 @@ Statements:
 * [If ... Then ... Else](../tB/Core/If-Then-Else) - execute code conditionally
 * [Continue](../tB/Core/Continue) - skip to the next iteration of the loop
 * [Exit](../tB/Core/Exit) - exit a loop, procedure, function or property
+* [Return](../tB/Core/Return) - return from a **GoSub** subroutine, or (twinBASIC) return a value and exit from a **Function** or **Property Get**
 * [Select Case](../tB/Core/Select-Case) - execute a code block selected by an expression
 * [With](../tB/Core/With) - bring a variable or expression into scope
 * [Goto](../tB/Core/GoTo), [GoSub ... Return](../tB/Core/GoSub-Return) - transfer execution to another location
@@ -81,6 +85,7 @@ Statements:
 * [Const](../tB/Core/Const) - declare a constant
 * [Public](../tB/Core/Public) - declare a public variable in a class or module
 * [Private](../tB/Core/Private) - declare a private variable in a class or module
+* [Protected](../tB/Core/Protected) - (twinBASIC) declare a class member accessible within the class and its derived classes
 * [Static](../tB/Core/Static) - declare a a variable of static duration
 
 ## Variable Assignment and Modification
@@ -89,9 +94,15 @@ Statements:
 
 - [Let](../tB/Core/Let) - sets the value of a variable
 - [Set](../tB/Core/Set) - changes the object referred by the variable
+- [New](../tB/Core/New) - create a new instance of a class
 - [LSet](../tB/Core/LSet) - assigns a user-defined type, or left-aligns a string
 - [RSet](../tB/Core/RSet) - right-aligns a string
 
+Operators:
+
+- [Is](../tB/Core/Is) - compares two object references for identity
+- [IsNot](../tB/Core/IsNot) - (twinBASIC) the logical inverse of **Is**
+
 ## Arrays
 
 Statements:

docs/Reference/Core/CoClass.md

@@ -0,0 +1,117 @@
+---
+title: CoClass
+parent: Statements
+permalink: /tB/Core/CoClass
+---
+# CoClass
+{: .no_toc }
+
+Defines a creatable COM class as a contract: a public name and identity, paired with one or more [**Interface**](Interface) blocks that the class will expose. The actual implementation lives in a separate [**Class**](Class) (typically `Private`) that uses [**Implements**](Implements).
+
+> [!NOTE]
+> The **CoClass** block is a twinBASIC extension. In classic VBA, coclasses could only be defined indirectly via a referenced type library (IDL/C++).
+
+Syntax:
+> [ *attributes* ]  
+> [ **Public** \| **Private** ] **CoClass** *name*  
+>      [ *member-attributes* ] **Interface** *interfacename*  
+>      ...  
+> **End CoClass**
+
+*attributes*
+: *optional*  Coclass-level attributes. See [Available attributes](#available-attributes) below.
+
+*name*
+: The identifier naming the coclass.
+
+*interfacename*
+: An [**Interface**](Interface) defined in the project (or imported from a referenced type library) that the coclass exposes. A coclass must list at least one interface and may list several.
+
+*member-attributes*
+: *optional*  Per-interface markers, principally:
+
+  - `[Default]` — marks an interface as the default interface of the coclass. It is conventional and highly recommended to mark exactly one interface as `[Default]`.
+  - `[Source]` — marks an interface as a source interface (an outgoing/event interface). Combine with `[Default]` (`[Default, Source]`) to mark the default event interface.
+
+**CoClass** blocks are valid only in `.twin` source files (not legacy `.bas` or `.cls` files), and must appear *before* the [**Class**](Class) or [**Module**](Module) statement in the file.
+
+### Available attributes
+
+- `[CoClassId("...")]` — fixes the CLSID for the coclass (a string GUID). Set this on any public/exported coclass so consumers in other projects bind to a stable identity.
+- `[Description("text")]` — exposed as the `helpstring` in the type library.
+- `[ComCreatable(True/False)]` — indicates whether the coclass can be created with **New**. `True` by default.
+- `[AppObject]` — marks the class as part of the global namespace. Use only when you fully understand the implication.
+- `[Hidden]` — hides the coclass from IntelliSense and similar lists.
+- `[CoClassCustomConstructor("ModuleName.FunctionName")]` — names a factory function (returning `HRESULT` and producing the new instance via an out parameter) used in place of the default `New` behavior. The factory may construct any private class that implements the coclass's interfaces.
+
+### Example
+
+A simple coclass exposing two interfaces, with `IFoo` marked as the default:
+
+```tb
+[CoClassId("52112FA1-FBE4-11CA-B5DD-0020AFE7292D")]
+CoClass Foo
+    [Default] Interface IFoo
+    Interface IBar
+End CoClass
+```
+
+A more complete example showing a custom-constructor coclass paired with a private implementing class. The coclass `Foo` is what consumers see and instantiate; the actual implementation `FooImpl` is hidden:
+
+```tb
+[InterfaceId("016BC30A-A8E0-4AAF-93AE-13BD838A149E")]
+Public Interface IFoo
+    Sub Foo()
+End Interface
+
+[InterfaceId("2A20E655-30A4-4534-86BC-6A7E281C425D")]
+Public Interface IBar
+    Sub Bar()
+End Interface
+
+[CoClassId("7980D953-10BF-478C-93BB-DD0093315D96")]
+[CoClassCustomConstructor("FooFactory.CreateFoo")]
+[ComCreatable(True)]
+Public CoClass Foo
+    [Default] Interface IFoo
+    Interface IBar
+End CoClass
+
+' The implementation does not have to be exposed.
+Private Class FooImpl
+    Implements IFoo
+    Implements IBar
+
+    Public Sub Foo() Implements IFoo.Foo
+        Debug.Print "Foo ran"
+    End Sub
+
+    Public Sub Bar() Implements IBar.Bar
+        Debug.Print "Bar ran"
+    End Sub
+End Class
+
+Public Module FooFactory
+    ' The signature must be "preserved", returning an HRESULT
+    ' and the new instance via the "out" parameter.
+    Public Function CreateFoo(ByRef RHS As Foo) As Long
+        Set RHS = New FooImpl
+        Return 0 ' S_OK
+    End Function
+End Module
+
+Public Module Test
+    Public Sub DoIt()
+        Dim MyFoo As Foo
+        Set MyFoo = New Foo  ' Implicitly calls FooFactory.CreateFoo.
+        MyFoo.Foo
+    End Sub
+End Module
+```
+
+### See Also
+
+- [**Interface** statement](Interface)
+- [**Implements** statement](Implements)
+- [**Class** statement](Class)
+- [Interfaces and CoClasses](../../Features/Language/Interfaces-CoClasses)

docs/Reference/Core/Deftype.md

@@ -0,0 +1,80 @@
+---
+title: Deftype
+parent: Statements
+permalink: /tB/Core/Deftype
+---
+# DefBool, DefByte, DefInt, DefLng, DefLngLng, DefLngPtr, DefCur, DefSng, DefDbl, DefDec, DefDate, DefStr, DefObj, DefVar
+{: .no_toc }
+
+Used at the module level to set the default data type for variables, arguments passed to procedures, and the return type for **Function** and **Property Get** procedures whose names start with the specified characters.
+
+> [!WARNING]
+> The **Def**_type_ family of statements is deprecated. They are supported for compatibility with legacy code, but new code should declare every variable, argument, and return type explicitly with **As** *type*. Combined with [**Option Explicit**](Option#Explicit), explicit declarations make code far easier to read and maintain.
+
+Syntax:
+
+- > **DefBool** *letterrange* [ **,** *letterrange* ] **. . .**
+- > **DefByte** *letterrange* [ **,** *letterrange* ] **. . .**
+- > **DefInt** *letterrange* [ **,** *letterrange* ] **. . .**
+- > **DefLng** *letterrange* [ **,** *letterrange* ] **. . .**
+- > **DefLngLng** *letterrange* [ **,** *letterrange* ] **. . .**
+- > **DefLngPtr** *letterrange* [ **,** *letterrange* ] **. . .**
+- > **DefCur** *letterrange* [ **,** *letterrange* ] **. . .**
+- > **DefSng** *letterrange* [ **,** *letterrange* ] **. . .**
+- > **DefDbl** *letterrange* [ **,** *letterrange* ] **. . .**
+- > **DefDec** *letterrange* [ **,** *letterrange* ] **. . .**
+- > **DefDate** *letterrange* [ **,** *letterrange* ] **. . .**
+- > **DefStr** *letterrange* [ **,** *letterrange* ] **. . .**
+- > **DefObj** *letterrange* [ **,** *letterrange* ] **. . .**
+- > **DefVar** *letterrange* [ **,** *letterrange* ] **. . .**
+
+*letterrange*
+: A single letter, or a hyphenated range *letter1*-*letter2*. The letters specify the leading character of names that adopt the default type. Case is not significant.
+
+The statement name determines the data type:
+
+| Statement | Data type |
+|:----------|:----------|
+| **DefBool**   | **Boolean** |
+| **DefByte**   | **Byte** |
+| **DefInt**    | **Integer** |
+| **DefLng**    | **Long** |
+| **DefLngLng** | **LongLong** |
+| **DefLngPtr** | **LongPtr** |
+| **DefCur**    | **Currency** |
+| **DefSng**    | **Single** |
+| **DefDbl**    | **Double** |
+| **DefDec**    | **Decimal** (not currently supported) |
+| **DefDate**   | **Date** |
+| **DefStr**    | **String** |
+| **DefObj**    | **Object** |
+| **DefVar**    | **Variant** |
+
+For example, in the following fragment, `Message` is a **String** variable:
+
+```tb
+DefStr A-Q
+. . .
+Message = "Out of stack space."
+```
+
+A **Def**_type_ statement affects only the module where it is used. The default data type for variables, arguments, and return types of items not declared explicitly and not covered by a **Def**_type_ statement is **Variant**.
+
+When you specify a letter range, it usually defines the data type for variables that begin with letters in the first 128 characters of the character set. However, when you specify the range A-Z, you set the default to the specified data type for *all* names, including those starting with characters from the extended part of the character set (128-255).
+
+After the range A-Z has been specified, you can't further redefine subranges by using **Def**_type_ statements. Once a range has been specified, including a previously defined letter in another **Def**_type_ statement is an error. You can, however, explicitly specify the data type of any variable — defined or not — by using a [**Dim**](Dim) statement with an **As** *type* clause:
+
+```tb
+DefInt A-Z
+Dim TaxRate As Double   ' explicit declaration overrides the default
+```
+
+**Def**_type_ statements don't affect elements of user-defined types — those must be explicitly declared.
+
+### See Also
+
+- [**Dim** statement](Dim)
+- [**Option** statement](Option) (for **Option Explicit**)
+- [**Type** statement](Type)
+
+{% include VBA-Attribution.md %}

docs/Reference/Core/Exit.md

@@ -6,7 +6,7 @@ permalink: /tB/Core/Exit
 # Exit
 {: .no_toc }
 
-Exits a block of **Do…Loop**, **For…Next**, **Function**,  **Sub**, or **Property** code.
+Exits a block of **Do…Loop**, **For…Next**, **While...Wend**, **Function**,  **Sub**, or **Property** code.
 
 Syntax:
 
@@ -16,6 +16,9 @@ Syntax:
 - **Exit For**  
   Provides a way to exit a **For** loop. It can be used only in a **[For...Next](For-Next)** or **[For Each...Next](For-Next)** loop. **Exit For** transfers control to the statement following the **Next** statement. When used within nested **For** loops, **Exit For** transfers control to the loop that is one nested level above the loop where **Exit For** occurs.
 
+- **Exit While**  
+  Provides a way to exit a **[While...Wend](While-Wend)** loop. It can be used only inside a **While...Wend** statement. **Exit While** transfers control to the statement following the **Wend** statement. When used within nested **While...Wend** statements, **Exit While** transfers control to the loop that is one nested level above the loop where **Exit While** occurs. **Exit While** is a twinBASIC extension; classic VBA has no early-exit form for **While...Wend**.
+
 - **Exit Function**  
   Immediately exits the **[Function](Function)** procedure in which it appears. Execution continues with the statement following the statement that called the **Function**.
 

docs/Reference/Core/Function.md

@@ -15,7 +15,7 @@ Syntax:
 >      [ [ **Let** ] *name* **=** *expression* ] ...  
 >      [ **Set** *name* **=** *expression* ] ...  
 >      [ **Return** *expression* ] ...  
->      [ **Exit Function** | **Return** ] ...  
+>      [ **Exit Function** ] ...  
 >      [ *statements* ] ...  
 > **End Function**
 
@@ -56,11 +56,11 @@ Syntax:
 **[Set](Set)**
 : *optional* Assigns an object-type return value of the **Function** without exiting the function.
 
-**[Return](Return)**
-: *optional* Immediately returns from the function. If an *expression* is provided, its value is used as the return value of the **Function**.
+**[Return](Return)** *expression*
+: *optional* Immediately returns from the function with *expression* as the return value. The *expression* is required in this form; a bare **Return** is reserved for the [**GoSub...Return**](GoSub-Return) construct and does not exit a **Function**.
 
 **[Exit Function](Exit)**
-: *optional* Immediately returns from the function.
+: *optional* Immediately returns from the function without setting a return value. Use this to leave a function early when no value needs to be returned (the function will yield its default return value: 0 for numeric types, `""` for strings, **Empty** for **Variant**, **Nothing** for object references).
 
 *expression*
 : *optional* Return value of the **Function**.
@@ -102,7 +102,7 @@ The **Friend** keyword can only be used in class modules. However, **Friend** pr
 
 All executable code must be in procedures. You can't define a **Function** procedure inside another **Function**, **[Sub](Sub)**, or **[Property](Property)** procedure.
 
-The **[Exit Function](Exit)** and **[Return](Return)** statements cause an immediate exit from a **Function** procedure. Program execution continues with the statement following the statement that called the **Function** procedure. Any number of **Exit Function** and **Return**  statements can appear anywhere in a **Function** procedure.
+The **[Exit Function](Exit)** statement and the **[Return](Return)** *expression* statement both cause an immediate exit from a **Function** procedure. Program execution continues with the statement following the statement that called the **Function** procedure. Any number of these statements can appear anywhere in a **Function** procedure. Use **Exit Function** when you've already assigned the return value (or want the default), and **Return** *expression* when you want to set the return value and exit in a single step.
 
 Like a **Sub** procedure, a **Function** procedure is a separate procedure that can take arguments, perform a series of statements, and change the values of its arguments. However, unlike a **Sub** procedure, you can use a **Function** procedure on the right side of an expression in the same way you use any intrinsic function, such as **Sqr**, **Cos**, or **Chr**, when you want to use the value returned by the function.