docs(classes): describe member methods and this semantics

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

5 files changed, 41 insertions, 18 deletions

diff --git a/doc/language/cpsc-language-overview.7.md b/doc/language/cpsc-language-overview.7.md
index d2d3617..21fbaff 100644
--- a/doc/language/cpsc-language-overview.7.md
+++ b/doc/language/cpsc-language-overview.7.md
@@ -16,7 +16,7 @@ Parenthesized type casts, such as (C_INT)Number, have unary precedence. C_INT, C
 
 Literals include integers, decimal real numbers, TRUE/FALSE, strings in double quotes, and single-byte characters in single quotes. Negative numbers use unary minus. There are no string or character escape sequences. Comments begin with `//` and continue to the end of the line.
 
-Declare variables before use. See DECLARE for built-in types and arrays, TYPE for records/enumerations/pointers, and CLASS for public/private fields.
+Declare variables before use. See DECLARE for built-in types and arrays, TYPE for records/enumerations/pointers, and CLASS for public/private fields and methods.
 
 The compiler extensions TRY/CATCH/ENDTRY and THROW support anonymous exceptions with stack unwinding. Runtime check failures print the source line and error reason to standard output before throwing and can be caught. An uncaught exception also prints a generic termination message and returns status 1. There is no error object or what() support.
 
@@ -41,7 +41,7 @@ The compiler extensions TRY/CATCH/ENDTRY and THROW support anonymous exceptions
 - [cpsc-keyword-closefile(7)](keyword/cpsc-keyword-closefile.7.md): close a text file.
 - [cpsc-keyword-type(7)](keyword/cpsc-keyword-type.7.md): define enumerations, pointers, and records.
 - [cpsc-keyword-c_type(7)](keyword/cpsc-keyword-c_type.7.md): import native C types and explicitly cast values.
-- [cpsc-keyword-class(7)](keyword/cpsc-keyword-class.7.md): define a class with public and private fields.
+- [cpsc-keyword-class(7)](keyword/cpsc-keyword-class.7.md): define a class with fields and methods.
 - [cpsc-keyword-and(7)](keyword/cpsc-keyword-and.7.md): combine conditions with logical AND.
 - [cpsc-keyword-or(7)](keyword/cpsc-keyword-or.7.md): combine conditions with logical OR.
 - [cpsc-keyword-not(7)](keyword/cpsc-keyword-not.7.md): negate a condition.
@@ -70,7 +70,7 @@ Closing and auxiliary keywords are documented with their main constructs: THEN/E
 
 # UNSUPPORTED FEATURES
 
-DATE, SET types and DEFINE, random-file operations (RANDOM/SEEK/GETRECORD/PUTRECORD), INT, RAND, string escapes, whole-array assignment or return, array fields, and class methods/constructors/destructors/inheritance (NEW/INHERITS/SUPER).
+DATE, SET types and DEFINE, random-file operations (RANDOM/SEEK/GETRECORD/PUTRECORD), INT, RAND, string escapes, whole-array assignment or return, array fields, and class constructors/destructors/inheritance (NEW/INHERITS/SUPER).
 
 The individual pages note relevant differences from the Cambridge 2026 pseudocode guide. This manual describes the compiler's current support.
 
diff --git a/doc/language/keyword/cpsc-keyword-call.7.md b/doc/language/keyword/cpsc-keyword-call.7.md
index 2d7c553..fd6718f 100644
--- a/doc/language/keyword/cpsc-keyword-call.7.md
+++ b/doc/language/keyword/cpsc-keyword-call.7.md
@@ -14,6 +14,8 @@ CALL name(arguments)
 
 Invoke a previously declared procedure with its parameters. Empty argument lists may be written `CALL name()` or `CALL name`. Use function calls in expressions to obtain their results. As compiler extensions, CALL also accepts functions and discards their results, and `name(arguments)` may stand alone without CALL for either a function or a procedure. Built-ins use the same argument checks in expressions and statements.
 
+Member calls accept `CALL Object.Method(arguments)` or the standalone form `Object.Method(arguments)`. With no arguments, `CALL Object.Method` is also accepted. Inside a method, use `this.Method(arguments)` for the current object; unqualified calls continue to name global functions or procedures. See [cpsc-keyword-class(7)](cpsc-keyword-class.7.md).
+
 # EXAMPLE
 
 ```text
@@ -25,4 +27,4 @@ CALL Hello()
 
 # SEE ALSO
 
-[cpsc-language-overview(7)](../cpsc-language-overview.7.md), [cpsc-keyword-procedure(7)](cpsc-keyword-procedure.7.md), [cpsc-keyword-function(7)](cpsc-keyword-function.7.md).
+[cpsc-language-overview(7)](../cpsc-language-overview.7.md), [cpsc-keyword-class(7)](cpsc-keyword-class.7.md), [cpsc-keyword-procedure(7)](cpsc-keyword-procedure.7.md), [cpsc-keyword-function(7)](cpsc-keyword-function.7.md).
diff --git a/doc/language/keyword/cpsc-keyword-class.7.md b/doc/language/keyword/cpsc-keyword-class.7.md
index 81276ac..faa84df 100644
--- a/doc/language/keyword/cpsc-keyword-class.7.md
+++ b/doc/language/keyword/cpsc-keyword-class.7.md
@@ -2,35 +2,52 @@
 
 # NAME
 
-cpsc-keyword-class, cpsc-keyword-public, cpsc-keyword-private, cpsc-keyword-endclass - define a class with public and private fields
+cpsc-keyword-class, cpsc-keyword-public, cpsc-keyword-private, cpsc-keyword-endclass - define a class with fields and methods
 
 # SYNOPSIS
 
 ```text
 CLASS name
-    PUBLIC field : type
-    PRIVATE field : type
+    PUBLIC publicField : type
+    PRIVATE privateField : type
+    PUBLIC PROCEDURE method(parameters)
+        statements
+    ENDPROCEDURE
+    FUNCTION getter(parameters) RETURNS type
+        RETURN expression
+    ENDFUNCTION
 ENDCLASS
 ```
 
 # DESCRIPTION
 
-Declare a class at top level with at least one field. Fields are public by default; PUBLIC or PRIVATE may be specified explicitly, without DECLARE. ENDCLASS closes the declaration.
+Declare a class at top level with at least one field or method. Fields and methods are public by default; PUBLIC or PRIVATE may be specified for each member. Fields do not use DECLARE. ENDCLASS closes the declaration. Fields and methods share a case-insensitive member namespace; duplicate names and method overloading are rejected.
 
-Classes use record value semantics: zero initialization, whole-value copying, arrays, pointers, and ordinary function/procedure parameters. Only public fields can be accessed externally. PRIVATE fields still initialize and copy with the whole value. Methods, constructors, destructors, NEW, INHERITS, and array fields are unsupported.
+Call methods as `Object.Method(arguments)` in expressions or as standalone statements, or use `CALL Object.Method(arguments)`. A receiver may be a variable, array element, nested field, or pointer dereference. Calls may precede definitions; methods may call later methods or recurse. Parameters and return values follow the ordinary FUNCTION and PROCEDURE rules. Access on function or method results remains unsupported.
+
+Within a method, bare field names refer to the current object's fields. The compiler extension `this` refers directly to the current object: use `this.Field` or `this.Method(arguments)` without pointer dereferencing. An unqualified call such as `Method(arguments)` still names a global function or procedure. PRIVATE members are accessible only from methods of the owning class, including access through another instance of that class.
+
+Parameters and local variables, arrays, or constants may shadow fields; this produces a warning with the source line and does not prevent compilation. The local name takes precedence; `this.Field` continues to access the field. The name `this` cannot be a class member or a method parameter or local declaration.
+
+Classes retain record value semantics: zero initialization, whole-value copying, arrays, pointers, and ordinary function/procedure parameters. Methods modify the receiver's storage. The object reference `this` may be read, returned, or passed as an object, including BYREF to a procedure; `this <- Other` copies Other into the current object without rebinding the reference. PRIVATE fields still initialize and copy with the whole value. Constructors, destructors, NEW, INHERITS, and array fields are unsupported.
 
 # EXAMPLE
 
 ```text
-CLASS Person
-    PUBLIC Name : STRING
-    PRIVATE Age : INTEGER
+CLASS Counter
+    PRIVATE Value : INTEGER
+    PUBLIC PROCEDURE Set(Number : INTEGER)
+        this.Value <- Number
+    ENDPROCEDURE
+    FUNCTION Get() RETURNS INTEGER
+        RETURN Value
+    ENDFUNCTION
 ENDCLASS
-DECLARE PersonValue : Person
-PersonValue.Name <- "Alice"
-OUTPUT PersonValue.Name
+DECLARE Item : Counter
+Item.Set(3)
+OUTPUT Item.Get()
 ```
 
 # SEE ALSO
 
-[cpsc-language-overview(7)](../cpsc-language-overview.7.md), [cpsc-keyword-type(7)](cpsc-keyword-type.7.md), [cpsc-keyword-declare(7)](cpsc-keyword-declare.7.md).
+[cpsc-language-overview(7)](../cpsc-language-overview.7.md), [cpsc-keyword-type(7)](cpsc-keyword-type.7.md), [cpsc-keyword-function(7)](cpsc-keyword-function.7.md), [cpsc-keyword-procedure(7)](cpsc-keyword-procedure.7.md), [cpsc-keyword-call(7)](cpsc-keyword-call.7.md).
diff --git a/doc/language/keyword/cpsc-keyword-function.7.md b/doc/language/keyword/cpsc-keyword-function.7.md
index 52efa90..c20bb50 100644
--- a/doc/language/keyword/cpsc-keyword-function.7.md
+++ b/doc/language/keyword/cpsc-keyword-function.7.md
@@ -21,6 +21,8 @@ As a compiler extension, `name(arguments)` may also be a complete statement that
 
 Parameters use `name : type`, optionally prefixed by BYVAL. BYVAL is the default; BYREF is forbidden for functions (guide section 8.3). Array parameters accept `ARRAY OF type` (one dimension) or `ARRAY[lower:upper, ...] OF type` (integer literal bounds). BYVAL arrays are copied. RETURNS, RETURN, BYVAL, and ENDFUNCTION belong here.
 
+A FUNCTION inside CLASS defines a member function, called as `Object.Method(arguments)`. It follows the same parameter and return rules. Within a method, use `this.Method(arguments)` to call another method on the current object; see [cpsc-keyword-class(7)](cpsc-keyword-class.7.md).
+
 # EXAMPLE
 
 ```text
@@ -32,4 +34,4 @@ OUTPUT Double(4)
 
 # SEE ALSO
 
-[cpsc-language-overview(7)](../cpsc-language-overview.7.md), [cpsc-keyword-procedure(7)](cpsc-keyword-procedure.7.md), [cpsc-keyword-call(7)](cpsc-keyword-call.7.md).
+[cpsc-language-overview(7)](../cpsc-language-overview.7.md), [cpsc-keyword-class(7)](cpsc-keyword-class.7.md), [cpsc-keyword-procedure(7)](cpsc-keyword-procedure.7.md), [cpsc-keyword-call(7)](cpsc-keyword-call.7.md).
diff --git a/doc/language/keyword/cpsc-keyword-procedure.7.md b/doc/language/keyword/cpsc-keyword-procedure.7.md
index 74c7024..f21ef59 100644
--- a/doc/language/keyword/cpsc-keyword-procedure.7.md
+++ b/doc/language/keyword/cpsc-keyword-procedure.7.md
@@ -18,6 +18,8 @@ Invoke with CALL. Parameters use `name : type`, optionally prefixed by BYVAL or
 
 Arrays accept `ARRAY OF type` or `ARRAY[lower:upper, ...] OF type`; explicit bounds must be integer literals. BYVAL copies the array; BYREF shares it. Bare RETURN can exit a procedure before a block terminator; RETURN with a value is invalid. BYVAL, BYREF, RETURN, and ENDPROCEDURE belong here. Calls may precede top-level definitions.
 
+A PROCEDURE inside CLASS defines a member procedure, called as `Object.Method(arguments)` or `CALL Object.Method(arguments)`. It follows the same parameter rules and modifies the receiver. Within a method, `this` refers directly to the current object; see [cpsc-keyword-class(7)](cpsc-keyword-class.7.md).
+
 # EXAMPLE
 
 ```text
@@ -31,4 +33,4 @@ OUTPUT Count
 
 # SEE ALSO
 
-[cpsc-language-overview(7)](../cpsc-language-overview.7.md), [cpsc-keyword-call(7)](cpsc-keyword-call.7.md), [cpsc-keyword-function(7)](cpsc-keyword-function.7.md).
+[cpsc-language-overview(7)](../cpsc-language-overview.7.md), [cpsc-keyword-class(7)](cpsc-keyword-class.7.md), [cpsc-keyword-call(7)](cpsc-keyword-call.7.md), [cpsc-keyword-function(7)](cpsc-keyword-function.7.md).