Document class semantics and inheritance policy

README.md

@@ -174,7 +174,6 @@ Long-form guides live in `docs/`:
 - `docs/compatibility.md` – supported Go versions and CI coverage notes.
 - `docs/versioning.md` – semantic versioning policy and compatibility contract.
 - `docs/deprecation_policy.md` – deprecation lifecycle for public Go embedding APIs.
-- `docs/pre_1_0_migration.md` – migration notes for known pre-1.0 breaking changes.
 - `docs/known_issues.md` – tracked P0/P1 correctness bug bar.
 - `ROADMAP.md` – versioned implementation checklist and release roadmap.
 - `templates/` – copy-friendly starter templates for common host integration patterns.

docs/classes.md

@@ -0,0 +1,161 @@
+# Classes
+
+VibeScript classes group related state and behavior using instance methods,
+class methods, instance variables, and class variables.
+
+Inheritance is not supported. Class definitions do not support
+subclassing or `super` calls.
+
+## Defining A Class
+
+Use `class ... end` to declare a class and `def ... end` for methods:
+
+```vibe
+class Counter
+  def initialize(start)
+    @count = start
+  end
+
+  def value
+    @count
+  end
+
+  def increment
+    @count = @count + 1
+  end
+end
+```
+
+Construct instances with `.new`:
+
+```vibe
+counter = Counter.new(10)
+counter.increment
+counter.value
+```
+
+If `initialize` is defined, `.new` forwards arguments to it.
+
+## Instance Methods vs Class Methods
+
+Instance methods:
+
+- Are declared with `def name`.
+- Are called on instances (`user.name`).
+
+Class methods:
+
+- Are declared with `def self.name`.
+- Are called on the class (`User.find(1)`).
+
+```vibe
+class Mathy
+  def self.twice(n)
+    n * 2
+  end
+
+  def call_twice(n)
+    self.class.twice(n)
+  end
+end
+```
+
+## Instance Variables (`@name`)
+
+Instance variables are per-object state:
+
+```vibe
+class Person
+  def initialize(name)
+    @name = name
+    @age = 0
+  end
+
+  def birthday
+    @age = @age + 1
+  end
+end
+```
+
+Shorthand parameter assignment is supported in method signatures:
+
+```vibe
+class Point
+  def initialize(@x, @y)
+  end
+end
+```
+
+## Class Variables (`@@name`)
+
+Class variables are shared by all instances of the same class within a script
+invocation:
+
+```vibe
+class Counter
+  @@instances = 0
+
+  def initialize
+    @@instances = @@instances + 1
+  end
+
+  def self.instances
+    @@instances
+  end
+end
+```
+
+## `property`, `getter`, And `setter`
+
+Inside a class body, you can generate accessor methods:
+
+- `property x` creates `x` and `x=`.
+- `getter x` creates `x`.
+- `setter x` creates `x=`.
+
+```vibe
+class Account
+  property balance
+  getter owner
+  setter nickname
+
+  def initialize(owner, balance)
+    @owner = owner
+    @balance = balance
+    @nickname = ""
+  end
+end
+```
+
+When assigning through a member (`obj.name = ...`):
+
+- If `name=` exists, VibeScript calls that setter method.
+- If only `name` exists (getter without setter), assignment raises a read-only
+  property error.
+
+## Privacy
+
+Mark methods private with `private def`:
+
+```vibe
+class Helper
+  private def secret
+    42
+  end
+
+  def call_internal
+    secret
+  end
+end
+```
+
+Private methods are callable only on the current receiver (the same instance or
+class context). Calls like `other.secret` raise a runtime `private method`
+error.
+
+## Common Errors
+
+- Calling a missing method: `unknown member ...` / `unknown class member ...`
+- Calling a private method externally: `private method ...`
+- Assigning to getter-only attributes: `cannot assign to read-only property ...`
+- Calling `.new` with wrong arguments for `initialize`: argument errors

docs/introduction.md

@@ -20,6 +20,7 @@ dives on specific topics.
 - `durations.md` – duration literals and time-based helper methods.
 - `time.md` – Time creation, formatting, accessors, and time/duration math.
 - `typing.md` – gradual typing: annotations, nullables, and type-checked calls.
+- `classes.md` – class syntax, class/instance methods, variables, and privacy.
 - `language_reference.md` – consolidated language syntax and semantics reference.
 - `syntax_compatibility.md` – core syntax freeze baseline and compatibility guarantees.
 - `control-flow.md` – conditionals, loops, and ranges.
@@ -40,5 +41,4 @@ dives on specific topics.
 - `compatibility.md` – supported Go versions and CI coverage expectations.
 - `versioning.md` – semantic versioning policy and compatibility contract.
 - `deprecation_policy.md` – lifecycle policy for public Go embedding APIs.
-- `pre_1_0_migration.md` – migration notes for all known pre-1.0 breaking changes.
 - `known_issues.md` – active P0/P1 correctness bug bar.

docs/language_reference.md

@@ -80,6 +80,11 @@ class Counter
 end
 ```
 
+Inheritance is not supported.
+
+See `docs/classes.md` for class methods, `@`/`@@` variables, accessors, and
+privacy semantics.
+
 ## Method Calls
 
 Calls support positional args and keyword args:

docs/versioning.md

@@ -36,4 +36,4 @@ This contract applies to:
 
 Go toolchain support follows `docs/compatibility.md`.
 Core language syntax guarantees are tracked in `docs/syntax_compatibility.md`.
-Pre-1.0 migration notes are tracked in `docs/pre_1_0_migration.md`.
+Pre-1.0 migration guidance is communicated in release notes and pull request descriptions.