Tweak Variables docs

Adjusts some doctrings and comments, and one error in typing.

Manpage has the introdctory Variables material updated a bit, and the
methods sorted, to match everywhere else in the manpage.

Signed-off-by: Mats Wichmann <[email protected]>

CHANGES.txt

@@ -174,6 +174,7 @@ RELEASE  VERSION/DATE TO BE FILLED IN LATER
     - A build Variable is now a dataclass, with initialization moving to
       the automatically provided method; the Variables class no longer
       writes directly to a Variable (makes static checkers happier).
+    - Improved Variables documentation.
     - The (optional) C Conditional Scanner now does limited macro
       replacement on the contents of CPPDEFINES, to improve finding deps
       that are conditionally included.  Previously replacement was only

RELEASE.txt

@@ -205,6 +205,8 @@ DOCUMENTATION
 
 - Update Clean and NoClean documentation.
 
+- Improved Variables documentation.
+
 DEVELOPMENT
 -----------
 

SCons/Tool/install.xml

@@ -77,7 +77,7 @@ a "live" location in the system.
 </para>
 
 <para>
-See also &FindInstalledFiles;.
+See also &f-link-FindInstalledFiles;.
 For more thoughts on installation, see the User Guide
 (particularly the section on Command-Line Targets
 and the chapters on Installing Files and on Alias Targets).

SCons/Variables/EnumVariable.py

@@ -77,19 +77,20 @@ def EnumVariable(
 ) -> tuple[str, str, str, Callable, Callable]:
     """Return a tuple describing an enumaration SCons Variable.
 
-    The input parameters describe a variable with only predefined values
-    allowed.  The value of *ignorecase* defines the behavior of the
+    An Enum Variable is an abstraction that allows choosing one
+    value from a provided list of possibilities (*allowed_values*).
+    The value of *ignorecase* defines the behavior of the
     validator and converter: if ``0``, the validator/converter are
     case-sensitive; if ``1``, the validator/converter are case-insensitive;
     if ``2``, the validator/converter are case-insensitive and the
     converted value will always be lower-case.
 
     Arguments:
-       key: variable name, passed directly through to the return tuple.
-       default: default values, passed directly through to the return tuple.
+       key: the name of the variable.
+       default: default value, passed directly through to the return tuple.
        help: descriptive part of the help text,
           will have the allowed values automatically appended.
-       allowed_values: list of the allowed values for this variable.
+       allowed_values: the values for the choice.
        map: optional dictionary which may be used for converting the
           input value into canonical values (e.g. for aliases).
        ignorecase: defines the behavior of the validator and converter.

SCons/Variables/ListVariable.py

@@ -185,23 +185,24 @@ def ListVariable(
     names: list[str],
     map: dict | None = None,
     validator: Callable | None = None,
-) -> tuple[str, str, str, None, Callable]:
+) -> tuple[str, str, str, Callable, Callable]:
     """Return a tuple describing a list variable.
 
-    The input parameters describe a list variable, where the values
-    can be one or more from *names* plus the special values ``all``
-    and ``none``.
+    A List Variable is an abstraction that allows choosing one or more
+    values from a provided list of possibilities (*names). The special terms
+    ``all`` and ``none`` are also provided to help make the selection.
 
     Arguments:
        key: the name of the list variable.
        help: the basic help message.  Will have text appended indicating
-          the allowable values (not including any extra names from *map*).
-       default: the default value(s) for the list variable. Can be
-          given as string (possibly comma-separated), or as a list of strings.
-          ``all`` or ``none`` are allowed as *default*. You can also simulate
-          a must-specify ListVariable by giving a *default* that is not part
-          of *names*, it will fail validation if not supplied.
-       names: the allowable values. Must be a list of strings.
+          the allowed values (not including any extra names from *map*).
+       default: the default value(s) for the list variable. Can be given
+          as string (use commas to -separated multiple values), or as a list
+          of strings.  ``all`` or ``none`` are allowed as *default*.
+          A must-specify ListVariable can be simulated by giving a value
+          that is not part of *names*, which will cause validation to fail
+          if the variable is not given in the input sources.
+       names: the values to choose from. Must be a list of strings.
        map: optional dictionary to map alternative names to the ones in
           *names*, providing a form of alias. The converter will make
           the replacement, names from *map* are not stored and will

SCons/Variables/__init__.py

@@ -225,13 +225,17 @@ def AddVariables(self, *optlist) -> None:
     def Update(self, env, args: dict | None = None) -> None:
         """Update an environment with the Build Variables.
 
-        Collects variables from the input sources which do not match
-        a variable description in this object. These are ignored for
-        purposes of adding to *env*, but can be retrieved using the
-        :meth:`UnknownVariables` method.  Also collects variables which
-        are set in *env* from the default in a variable description and
-        not from the input sources. These are available in the
-        :attr:`defaulted` attribute.
+        This is where the work of adding variables to the environment
+        happens, The input sources saved at init time are scanned for
+        variables to add, though if *args* is passed, then it is used
+        instead of the saved one. If any variable description set up
+        a callback for a validator and/or converter, those are called.
+        Variables from the input sources which do not match a variable
+        description in this object are ignored for purposes of adding
+        to *env*, but are saved in the :attr:`unknown` dict attribute.
+        Variables which are set in *env* from the default in a variable
+        description and not from the input sources are saved in the
+        :attr:`defaulted` list attribute.
 
         Args:
             env: the environment to update.
@@ -242,7 +246,7 @@ def Update(self, env, args: dict | None = None) -> None:
         values = {opt.key: opt.default for opt in self.options if opt.default is not None}
         self.defaulted = list(values)
 
-        # next set the values specified in any options script(s)
+        # next set the values specified in any saved-variables script(s)
         for filename in self.files:
             # TODO: issue #816 use Node to access saved-variables file?
             if os.path.exists(filename):
@@ -288,8 +292,16 @@ def Update(self, env, args: dict | None = None) -> None:
             if not added:
                 self.unknown[arg] = value
 
-        # put the variables in the environment:
+        # put the variables in the environment
         # (don't copy over variables that are not declared as options)
+        #
+        # Nitpicking: in OO terms, this method increases coupling as its
+        #   main work is to update a different object (env), rather than
+        #   the object it's bound to (although it does update self, too).
+        #   It's tricky to decouple because the algorithm counts on directly
+        #   setting a var in *env* first so it can call env.subst() on it
+        #   to transform it.
+
         for option in self.options:
             try:
                 env[option.key] = values[option.key]
@@ -400,9 +412,10 @@ def GenerateHelpText(self, env, sort: bool | Callable = False) -> str:
                 (must take two arguments and return ``-1``, ``0`` or ``1``)
                 or a boolean to indicate if it should be sorted.
         """
-        # TODO the 'sort' argument matched the old way Python's sorted()
-        #   worked, taking a comparison function argument. That has been
-        #   removed so now we have to convert to a key.
+        # TODO this interface was designed when Pythin sorted() took an
+        #   optional comparison function (pre-3.0). Since it no longer does,
+        #   we use functools.cmp_to_key() since can't really change the
+        #   documented meaning of the "sort" argument. Maybe someday?
         if callable(sort):
             options = sorted(self.options, key=cmp_to_key(lambda x, y: sort(x.key, y.key)))
         elif sort is True: