# HG changeset patch # User Christian Brabandt # Date 1704639609 -3600 # Node ID 8241df3e6dc1a93496735495276657ac47b54086 # Parent e03147dea049fc44bc5663ecb20e749e23d2167b runtime(doc): Improve the documentation for Vim9 classes (#13828) Commit: https://github.com/vim/vim/commit/b21499537fb9fd0ff407e6113ac60ebd82058e2a Author: Aliaksei Budavei <32549825+zzzyxwvut@users.noreply.github.com> Date: Sun Jan 7 17:52:10 2024 +0300 runtime(doc): Improve the documentation for Vim9 classes (https://github.com/vim/vim/issues/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 Signed-off-by: Yegappan Lakshmanan Signed-off-by: Christian Brabandt diff --git a/runtime/doc/vim9class.txt b/runtime/doc/vim9class.txt --- 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" ca 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-classe 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 r 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 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, alt < *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 - 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 < 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 t 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 coul 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