docs(classes): describe member methods and this semantics

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

4 files changed, 38 insertions, 15 deletions

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).