runtime(doc): Improve the documentation for Vim9 classes (#13828)

* Emend textual typos
* Emend syntactic errors in examples
* Acknowledge no support for abstract static methods
* Acknowledge the non-ubiquity of instance qualification

"This" was never allowed in method declarations, e.g.:
    class A
        def this.M()
        enddef
    endclass

and, since patch 9.0.2167, "this" can no longer be used in field
declarations, e.g.:
    class B
        var this.f: string
    endclass

* Recognise abstract child classes
* Reword an ambiguous turn of phrase

Signed-off-by: Aliaksei Budavei <0x000c70@gmail.com>
Signed-off-by: Ernie Rael <errael@raelity.com>
Signed-off-by: Yegappan Lakshmanan <yegappan@yahoo.com>
Signed-off-by: Christian Brabandt <cb@256bit.org>

diff --git a/runtime/doc/vim9class.txt b/runtime/doc/vim9class.txt
index ca9daffac55715898ba5492237d3317ec18ecd4b..6e94e84832e2fb12e864fee3760df199570bc1b9 100644 (file)
--- a/runtime/doc/vim9class.txt
+++ b/runtime/doc/vim9class.txt
@@ -1,4 +1,4 @@
-*vim9class.txt*        For Vim version 9.1.  Last change: 2024 Jan 01
+*vim9class.txt*        For Vim version 9.1.  Last change: 2024 Jan 06
 
 
                  VIM REFERENCE MANUAL    by Bram Moolenaar
@@ -106,17 +106,17 @@ The object variables "lnum" and "col" can be accessed directly: >
        echo $'The text position is ({pos.lnum}, {pos.col})'
 <                                                  *E1317* *E1327* *:this*
 If you have been using other object-oriented languages you will notice that in
-Vim, within a class definition, the object members are consistently referred
-to with the "this." prefix.  This is different from languages like Java and
-TypeScript.  The naming convention makes the object members easy to spot.
-Also, when a variable does not have the "this." prefix you know it is not an
-object variable.
+Vim, within a class definition, the declared object members are consistently
+referred to with the "this." prefix.  This is different from languages like
+Java and TypeScript.  The naming convention makes the object members easy to
+spot.  Also, when a variable does not have the "this." prefix you know it is
+not an object variable.
                                                                *E1411*
 From outside the class definition, access an object's methods and variables by
 using the object name followed by a dot following by the member: >
 
        pos.lnum
-       pos.setCol(10)
+       pos.SetCol(10)
 <
                                                        *E1405* *E1406*
 A class name cannot be used as an expression.  A class name cannot be used in
@@ -164,7 +164,7 @@ from outside the class or its sub-classes, you can make them protected.  This
 is done by prefixing an underscore to the name: >
 
        var _lnum: number
-       var _col number
+       var _col: number
 
 Now you need to provide methods to get the value of the protected variables.
 These are commonly called getters.  We recommend using a name that starts with
@@ -174,7 +174,7 @@ These are commonly called getters.  We recommend using a name that starts with
           return this._lnum
        enddef
 
-       def GetCol() number
+       def GetCol(): number
           return this._col
        enddef
 
@@ -330,7 +330,8 @@ variables but they have no access to the object variables, they cannot use the
 
 Inside the class the class method can be called by name directly, outside the
 class the class name must be prefixed: `OtherThing.ClearTotalSize()`.  To use
-a super class method in a child class, the class name must be prefixed.
+a class method from a parent class in a child class, the class name must be
+prefixed.
 
 Just like object methods the access can be made protected by using an
 underscore as the first character in the method name: >
@@ -492,17 +493,15 @@ prefix when defining the method: >
 
        abstract class Shape
           abstract def Draw()
-          abstract static def SetColor()
        endclass
 <
 A static method in an abstract class cannot be an abstract method.
 
                                                *E1373*
-A class extending the abstract class must implement all the abstract methods.
-The signature (arguments, argument types and return type) must be exactly the
-same.  If the return type of a method is a class, then that class or one of
-its subclasses can be used in the extended method.  Class methods in an
-abstract class can also be abstract methods.
+A non-abstract class extending the abstract class must implement all the
+abstract methods.  The signature (arguments, argument types and return type)
+must be exactly the same.  If the return type of a method is a class, then
+that class or one of its subclasses can be used in the extended method.
 
 ==============================================================================
 
@@ -610,7 +609,7 @@ once.  They can appear in any order, although this order is recommended: >
 <                                                      *E1355* *E1369*
 Each variable and method name can be used only once.  It is not possible to
 define a method with the same name and different type of arguments.  It is not
-possible to use a public and protected member variable with the same name.  A
+possible to use a public and protected member variable with the same name.  An
 object variable name used in a super class cannot be reused in a child class.
 
 
@@ -688,7 +687,7 @@ Inside a class, in between `:class` and `:endclass`, these items can appear:
 - A class variable declaration: >
        static var _protectedClassVariableName: memberType
        static var readonlyClassVariableName: memberType
-       static var public readwriteClassVariableName: memberType
+       public static var readwriteClassVariableName: memberType
 - A constructor method: >
        def new(arguments)
        def newName(arguments)
@@ -747,7 +746,7 @@ null object ~
 When a variable is declared to have the type of an object, but it is not
 initialized, the value is null.  When trying to use this null object Vim often
 does not know what class was supposed to be used.  Vim then cannot check if
-a variable name is correct and you will get an "Using a null object" error,
+a variable name is correct and you will get a "Using a null object" error,
 even when the variable name is invalid. *E1360* *E1362*
 
 
@@ -787,7 +786,7 @@ the name, you can define the constructor like this: >
 <
 When using the default new() method, if the order of the object variables in
 the class is changed later, then all the callers of the default new() method
-needs to change.  To avoid this, the new() method can be explicitly defined
+need to change.  To avoid this, the new() method can be explicitly defined
 without any arguments.
 
                                                        *E1328*
@@ -993,7 +992,7 @@ in the body, while for other variables this is not needed and often omitted.
 This leads to a mix of variables with and without "this.", which is
 inconsistent.
 
-For |Vim9| classes the "this." prefix is always used.  Also for declaring the
+For |Vim9| classes the "this." prefix is always used for declared methods and
 variables.  Simple and consistent.  When looking at the code inside a class
 it's also directly clear which variable references are object variables and
 which aren't.
@@ -1029,7 +1028,7 @@ Following that Vim object variables could be declared like this: >
        endclass
 
 Some users pointed out that this looks more like an assignment than a
-declaration.  Adding "var" changes that: >
+declaration.  Adding "var" and omitting "this." changes that: >
        class Point
          var x: number
          var y = 0