Docstring error in resolve_matching_names and resolve_matching_names_values: preserve_order description is inverted #4493
Description
Noting a mistake in the docstring for isaaclab.utils.string.resolve_matching_names: the text description incorrectly describes how the function works under preserve_order=True and preserve_order=False.
"""
...
If the :attr:`preserve_order` is True, the ordering of the matched indices and names is the same as the order
of the provided list of strings. This means that the ordering is dictated by the order of the target strings
and not the order of the query regular expressions.
If the :attr:`preserve_order` is False, the ordering of the matched indices and names is the same as the order
of the provided list of query regular expressions.
For example, consider the list of strings is ['a', 'b', 'c', 'd', 'e'] and the regular expressions are ['a|c', 'b'].
If :attr:`preserve_order` is False, then the function will return the indices of the matched strings and the
strings as: ([0, 1, 2], ['a', 'b', 'c']). When :attr:`preserve_order` is True, it will return them as:
([0, 2, 1], ['a', 'c', 'b']).
...
"""
In terms of the actual function operation, matched strings are enumerated in the order of the list of strings, and then only reordered to the query keys if preserve_order=True. This is the opposite of what the text describes. Swapping True and False in the above text will fix the documentation issue. The provided examples in the docstring are already correct according to the function's operation.
The same issue is seen in isaaclab.utils.string.resolve_matching_names_values directly below the other function.
"""
...
If the :attr:`preserve_order` is True, the ordering of the matched indices and names is the same as the order
of the provided list of strings. This means that the ordering is dictated by the order of the target strings
and not the order of the query regular expressions.
If the :attr:`preserve_order` is False, the ordering of the matched indices and names is the same as the order
of the provided list of query regular expressions.
For example, consider the dictionary is {"a|d|e": 1, "b|c": 2}, the list of strings is ['a', 'b', 'c', 'd', 'e'].
If :attr:`preserve_order` is False, then the function will return the indices of the matched strings, the
matched strings, and the values as: ([0, 1, 2, 3, 4], ['a', 'b', 'c', 'd', 'e'], [1, 2, 2, 1, 1]). When
:attr:`preserve_order` is True, it will return them as: ([0, 3, 4, 1, 2], ['a', 'd', 'e', 'b', 'c'], [1, 1, 1, 2, 2]).
...
"""
There is a typo/comma error in the example sentence:
... return the indices of the matched strings, the matched strings, and the values as: ...
(remove the redundant "the matched strings,")
This small doc fix will help avoid confusion for the use of other downstream functionalities, like in isaaclab.assets.Articulation:
"""
...
Find joints in the articulation based on the name keys.
Please see the :func:`isaaclab.utils.string.resolve_matching_names` function for more information
on the name matching.
...
"""
Thanks!