runtime(doc): Update the 'specifies' keyword documentation, slightly reformat

closes: #16648

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 5e5c28e9e378836e569eefbcfd70897fd312f655..7ba91e7d927207ed95533380722b9933e09e56c1 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: 2025 Feb 11
+*vim9class.txt*        For Vim version 9.1.  Last change: 2025 Feb 16
 
 
                  VIM REFERENCE MANUAL    by Bram Moolenaar
@@ -52,7 +52,6 @@ An interface is used to specify properties of an object:
 The class hierarchy allows for single inheritance.  Otherwise interfaces are
 to be used where needed.
 
-
 Class modeling ~
 
 You can model classes any way you like.  Keep in mind what you are building,
@@ -122,7 +121,6 @@ using the object name followed by a dot following by the member: >
 A class name cannot be used as an expression.  A class name cannot be used in
 the left-hand-side of an assignment.
 
-
 Object variable write access ~
                                                    *read-only-variable*
 Now try to change an object variable directly: >
@@ -626,13 +624,15 @@ once.  They can appear in any order, although this order is recommended: >
        extends ClassName
        implements InterfaceName, OtherInterface
        specifies SomeInterface
-<                                                      *E1355* *E1369*
+<
+The "specifies" feature is currently not implemented.
+
+                                                       *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.  An
 object variable name used in a super class cannot be reused in a child class.
 
-
 Object Variable Initialization ~
 
 If the type of a variable is not explicitly specified in a class, then it is
@@ -689,13 +689,12 @@ A class can implement one or more interfaces.  The "implements" keyword can
 only appear once *E1350* .  Multiple interfaces can be specified, separated by
 commas.  Each interface name can appear only once. *E1351*
 
-
 A class defining an interface ~
                                                        *specifies*
 A class can declare its interface, the object variables and methods, with a
 named interface.  This avoids the need for separately specifying the
 interface, which is often done in many languages, especially Java.
-
+TODO: This is currently not implemented.
 
 Items in a class ~
                                                *E1318* *E1325* *E1388*
@@ -736,25 +735,25 @@ Some of the builtin functions like |empty()|, |len()| and |string()| can be
 used with an object.  An object can implement a method with the same name as
 these builtin functions to return an object-specific value.
 
-                                                       *E1412*
+                                                       *E1412*
 The following builtin methods are supported:
-                                                       *object-empty()*
+                                                       *object-empty()*
     empty()  Invoked by the |empty()| function to check whether an object is
             empty.  If this method is missing, then true is returned.  This
             method should not accept any arguments and must return a boolean.
-                                                       *object-len()*
+                                                       *object-len()*
     len()    Invoked by the |len()| function to return the length of an
             object.  If this method is missing in the class, then an error is
             given and zero is returned.  This method should not accept any
             arguments and must return a number.
-                                                       *object-string()*
+                                                       *object-string()*
     string() Invoked by the |string()| function to get a textual
             representation of an object.  Also used by the |:echo| command
             for an object.  If this method is missing in the class, then a
             built-in default textual representation is used.  This method
             should not accept any arguments and must return a string.
 
-                                                       *E1413*
+                                                       *E1413*
 A class method cannot be used as a builtin method.
 
 Defining an interface ~
@@ -786,7 +785,6 @@ An interface can only be defined in a |Vim9| script file.  *E1342*
 An interface cannot "implement" another interface but it can "extend" another
 interface. *E1381*
 
-
 null object ~
 
 When a variable is declared to have the type of an object, but it is not
@@ -795,7 +793,6 @@ does not know what class was supposed to be used.  Vim then cannot check if
 a variable name is correct and you will get a "Using a null object" error,
 even when the variable name is invalid. *E1360* *E1362*
 
-
 Default constructor ~
                                                        *default-constructor*
 In case you define a class without a new() method, one will be automatically
@@ -1118,7 +1115,6 @@ For |Vim9| script using the same method name for all constructors seemed like
 the right choice, and by calling it new() the relation between the caller and
 the method being called is obvious.
 
-
 No overloading of the constructor ~
 
 In Vim script, both legacy and |Vim9| script, there is no overloading of
@@ -1139,7 +1135,6 @@ That way multiple constructors with different arguments are possible, while it
 is very easy to see which constructor is being used.  And the type of
 arguments can be properly checked.
 
-
 No overloading of methods ~
 
 Same reasoning as for the constructor: It is often not obvious what type
@@ -1148,7 +1143,6 @@ actually being called.  Better just give the methods a different name, then
 type checking will make sure it works as you intended.  This rules out
 polymorphism, which we don't really need anyway.
 
-
 Single inheritance and interfaces ~
 
 Some languages support multiple inheritance.  Although that can be useful in
@@ -1164,7 +1158,6 @@ it will be checked if that change was also changed.  The mechanism to assume a
 class implements an interface just because the methods happen to match is
 brittle and leads to obscure problems, let's not do that.
 
-
 Using "this.variable" everywhere ~
 
 The object variables in various programming languages can often be accessed in
@@ -1183,7 +1176,6 @@ 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.
 
-
 Using class variables ~
 
 Using "static variable" to declare a class variable is very common, nothing
@@ -1197,7 +1189,6 @@ the class.  This has two problems: The class name can be rather long, taking
 up quite a bit of space, and when the class is renamed all these places need
 to be changed too.
 
-
 Declaring object and class variables ~
 
 The main choice is whether to use "var" as with variable declarations.
@@ -1251,7 +1242,6 @@ function declaration syntax for class/object variables and methods.  Vim9 also
 reuses the general function declaration syntax for methods.  So, for the sake
 of consistency, we require "var" in these declarations.
 
-
 Using "ClassName.new()" to construct an object ~
 
 Many languages use the "new" operator to create an object, which is actually
@@ -1315,7 +1305,6 @@ An alternative would have been using the "protected" keyword, just like
 "public" changes the access in the other direction.  Well, that's just to
 reduce the number of keywords.
 
-
 No private object variables ~
 
 Some languages provide several ways to control access to object variables.