doc: desc. refresh only modules requiring it

Author: xdelaruelle

NEWS.rst

@@ -144,6 +144,8 @@ Modules 5.2.0 (not yet released)
   terminology.
 * Mark loaded modules that could benefit from a refresh evaluation in the
   :envvar:`__MODULES_LMREFRESH` environment variable.
+* Optimize :subcmd:`refresh` sub-command to only evaluate loaded modules that
+  defines volatile environment changes (shell completion, alias or function).
 
 .. _Nagelfar: http://nagelfar.sourceforge.net/
 .. _ShellCheck: https://www.shellcheck.net/

doc/source/changes.rst

@@ -839,6 +839,11 @@ The following module sub-commands appeared on Modules 5.
  * the :option:`--starts-with` and :option:`--contains` options are supported
    on this sub-command to provide the regular search match capabilities.
 
+:subcmd:`refresh`
+
+ Starting Modules 5.2, only the loaded modules listed in the
+ :envvar:`__MODULES_LMREFRESH` environment variables are refreshed.
+
 :subcmd:`restore`
 
  Starting Modules 5.2, initial environment is restored when specified

doc/source/module.rst

@@ -1686,16 +1686,20 @@ Module Sub-Commands
 .. subcmd:: refresh
 
  Force a refresh of all non-persistent components of currently loaded modules.
- This should be used on derived shells where shell aliases or shell functions
- need to be reinitialized but the environment variables have already been set
- by the currently loaded modules.
+ This should be used on derived shells where shell completions, shell aliases
+ or shell functions need to be reinitialized but the environment variables
+ have already been set by the currently loaded modules.
 
  Loaded modules are evaluated in ``refresh`` mode following their load order.
- In this evaluation mode only the :mfcmd:`set-alias` and :mfcmd:`set-function`
- modulefile commands will produce environment changes. Other modulefile
- commands that produce environment changes (like :mfcmd:`setenv` or
- :mfcmd:`append-path`) are ignored during a ``refresh`` evaluation as their
- changes should already be applied.
+ In this evaluation mode only the :mfcmd:`complete`, :mfcmd:`set-alias` and
+ :mfcmd:`set-function` modulefile commands will produce environment changes.
+ Other modulefile commands that produce environment changes (like
+ :mfcmd:`setenv` or :mfcmd:`append-path`) are ignored during a ``refresh``
+ evaluation as their changes should already be applied.
+
+ Only the loaded modules defining non-persistent environment changes are
+ evaluated in ``refresh`` mode. Such loaded modules are listed in the
+ :envvar:`__MODULES_LMREFRESH` environment variable.
 
  .. only:: html
 
@@ -1705,6 +1709,9 @@ Module Sub-Commands
     .. versionchanged:: 5.0
        Behavior of version 3.2 :subcmd:`refresh` sub-command restored
 
+    .. versionchanged:: 5.2
+       Only evaluate modules listed in :envvar:`__MODULES_LMREFRESH`
+
 .. subcmd:: reload
 
  Unload then load all loaded *modulefiles*.