# HG changeset patch
# User Christian Brabandt <cb@256bit.org>
# Date 1712261705 -7200
# Node ID 5914f369ff5b8e7de84327ff6b4db362532d3bcd
# Parent  e1df51f687363ba88035e81782c18d6a99869b8b
runtime(doc): Fill in a few details regarding :enums (#14349)

Commit: https://github.com/vim/vim/commit/957402258053ac639575749c6e41ec284f25ae1c
Author: Aliaksei Budavei <32549825+zzzyxwvut@users.noreply.github.com>
Date:   Thu Apr 4 23:05:33 2024 +0300

    runtime(doc): Fill in a few details regarding :enums (https://github.com/vim/vim/issues/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>

diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt
--- 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 ret
 		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
--- 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
 	   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
     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