doc: desc. one variant set multiple times on search context

NEWS.rst

@@ -29,6 +29,10 @@ Modules 5.3.1 (not yet released)
   available in several modulepaths. (fix issue #497)
 * Do not match module commands with :mfcmd:`--not-req<module>` option set on
   ``require`` or ``incompat`` extra specifier queries. (fix issue #498)
+* When one variant is specified multiple times on search context
+  (:subcmd:`avail`, :subcmd:`paths` or :subcmd:`whatis` sub-commands),
+  available modules returned are those providing all variant values set. (fix
+  issue #499)
 
 .. _Hunspell: https://hunspell.github.io/
 

doc/source/changes.rst

@@ -900,6 +900,8 @@ The following module sub-commands appeared on Modules 5.
 
  * variant specified in search query is taken into account to return available
    modules matching the variant specification.
+ * when one variant is specified multiple times in search query, returned
+   modules are those providing all the specified variant values.
  * Search query with just a variant set (no module name and version) is
    accepted.
  * :ref:`Extra specifier` is accepted in search query to query content of

doc/source/design/extra-match-search.rst

@@ -338,12 +338,19 @@ module* context:
 * multiple variants mentioned act as an *AND* operation
 
   * ``module avail mod/1.0 foo=val1 bar=val2``
-  * means *foo* equals *val1* and *bar* equals *val2*
+  * means module defines *foo* variant with *val1* as an available value and
+    *bar* variant with *val2* as an available value
 
-* same variant mentioned multiple times: only the last mention is retained
+* same variant mentioned multiple times: all mentions retained and act as an
+  *AND* operation
 
   * ``module avail mod/1.0 foo=val1 foo=val2``
-  * means *foo* equals *val2*
+  * means module defines *foo* variant with *val1* and *val2* as available
+    values
+
+Behavior for a single variant specified multiple times is adapted on *return
+all matching modules* context to be the same as a single extra specifier set
+multiple times.
 
 In extra match search query, extra specifiers are expressed with *name:value*
 syntax. Using *:* as separator helps to distinguish from variant

doc/source/module.rst

@@ -2776,6 +2776,13 @@ evaluation. Variants defined in modulefile are collected during this
 evaluation then compared to the variants specified in search query. If there
 is a match, module is included in search results otherwise it is withdrawn.
 
+When searching for available modules, if one variant is specified multiple
+times, matching modules are those providing all specified variant values. For
+instance ``bar=value1 bar=value2`` will return modules defining a ``bar``
+variant with ``value1`` and ``value2`` as available values. On a module
+selection context, only the last specified value is retained. Which means on
+previous example that ``bar`` variant is set to ``value2``.
+
 Module variants are reported along the module they are associated to on
 :subcmd:`list` sub-command results. They are also reported on :subcmd:`avail`
 sub-command if specified in search query or added to the element to report in