runtime(doc): Fill in a few details regarding :enums (#14349)

- Mention the support of eval() for enumeration values.

- Clarify the extent of immutability for enumeration values.

- Specify the requirements for class methods to meet for
  class variable initialisation and their use in nested
  functions and lambda expressions.

- Remove a duplicate sentence that describes how to access
  parent class methods in derivative classes (see another
  "copy" two paragraphs below).


Signed-off-by: Aliaksei Budavei <0x000c70@gmail.com>
Signed-off-by: Christian Brabandt <cb@256bit.org>

2 files changed, 27 insertions, 9 deletions

diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt
index 088daa75a3..6a4c8d981f 100644
--- a/runtime/doc/builtin.txt
+++ b/runtime/doc/builtin.txt
@@ -1,4 +1,4 @@
-*builtin.txt*	For Vim version 9.1.  Last change: 2024 Mar 29
+*builtin.txt*	For Vim version 9.1.  Last change: 2024 Apr 03
 
 
 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
@@ -2307,7 +2307,8 @@ eval({string})	Evaluate {string} and return the result.  Especially useful to
 		turn the result of |string()| back into the original value.
 		This works for Numbers, Floats, Strings, Blobs and composites
 		of them.  Also works for |Funcref|s that refer to existing
-		functions.
+		functions.  In |Vim9| script, it can be used to obtain |enum|
+		values from their fully qualified names.
 
 		Can also be used as a |method|: >
 			argv->join()->eval()
diff --git a/runtime/doc/vim9class.txt b/runtime/doc/vim9class.txt
index 8820d77b54..804e02dc17 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 Mar 28
+*vim9class.txt*	For Vim version 9.1.  Last change: 2024 Apr 04
 
 
 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
@@ -328,10 +328,27 @@ variables but they have no access to the object variables, they cannot use the
 	   enddef
 	endclass
 
-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 class method from a parent class in a child class, the class name must be
-prefixed.
+Inside the class, the class method can be called by name directly, outside the
+class, the class name must be prefixed: `OtherThing.ClearTotalSize()`.  Also,
+the name prefix must be used for public class methods in the special contexts
+of class variable initializers and of lambda expressions and nested functions:
+>
+    class OtherThing
+	static var name: string = OtherThing.GiveName()
+
+	static def GiveName(): string
+	    def DoGiveName(): string
+		return OtherThing.NameAny()
+	    enddef
+
+	    return DoGiveName()
+	enddef
+
+	static def NameAny(): string
+	    return "any"
+	enddef
+    endclass
+<
 
 Just like object methods the access can be made protected by using an
 underscore as the first character in the method name: >
@@ -972,8 +989,8 @@ The following example shows an enum with object variables and methods: >
     echo Planet.Earth.has_rings
 <
 						*E1421* *E1423* *E1424* *E1425*
-Enums and their values are immutable. They cannot be modified after
-declaration and cannot be utilized as numerical or string types.
+Enums and their values are immutable.  They cannot be utilized as numerical or
+string types.  Enum values can declare mutable instance variables.
 
 						*enum-name*
 Each enum value object has a "name" instance variable which contains the name