summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorAliaksei Budavei <32549825+zzzyxwvut@users.noreply.github.com>2024-01-07 17:52:10 +0300
committerGitHub <noreply@github.com>2024-01-07 15:52:10 +0100
commitb21499537fb9fd0ff407e6113ac60ebd82058e2a (patch)
treeec185bc53a650a2b07cc8b3a6fd227618afcb3db
parent5d5cbb2b9ac526fb6fad2116e24a282affc45efe (diff)
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>
-rw-r--r--runtime/doc/vim9class.txt43
1 files changed, 21 insertions, 22 deletions
diff --git a/runtime/doc/vim9class.txt b/runtime/doc/vim9class.txt
index ca9daffac5..6e94e84832 100644
--- 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