docs: clarify preserve_order descriptions and fix comma typo in string utils

[Ottohere-Mourn]

Summary

• Clarified the preserve_order parameter descriptions in resolve_matching_names and resolve_matching_names_values
• The original wording ("the ordering is the same as the order of") could be misread as describing the opposite behavior
• Changed to explicit language: False = iteration order of target strings, True = reordered to follow query key order
• Fixed a redundant phrase in the second function's docstring example text

Fixes #4493

Test Plan

• Docstrings now clearly describe the actual function behavior shown by the existing examples
• No code logic changes — documentation only

🤖 Generated with Claude Code

[isaaclab-review-bot]

📝 Review Summary

Verdict: Minor suggestion — the docstring clarifications for preserve_order are a clear improvement. One small note below about the example description in resolve_matching_names_values.

Overall: The rewording from "the ordering is the same as the order of" to explicit "returned in iteration order" / "reordered to follow the order of" is much clearer and easier to parse. Good fix for #4493.

[isaaclab-review-bot]

Nitpick (non-blocking): This line removes the mention of "the matched strings" (the second return element) from the example description — the original read: "the indices of the matched strings, the matched strings, and the values as".

The 3-tuple in the example still clearly shows all three return elements (indices, names, values), so it's understandable in context, but mentioning all three keeps the text perfectly aligned with the return structure.

Also, this single line is now quite long (~160 chars). Consider wrapping it for readability:

Suggested change

	If :attr:`preserve_order` is False, then the function will return the indices of the matched strings and the values as: ([0, 1, 2, 3, 4], ['a', 'b', 'c', 'd', 'e'], [1, 2, 2, 1, 1]). When
	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

This restores the description of all three return elements and keeps the line length reasonable.

[greptile-apps]

Greptile Summary

This PR rewrites the preserve_order parameter descriptions in resolve_matching_names and resolve_matching_names_values to be more explicit about ordering behavior, and collapses a two-line example sentence in the second function.

• The preserve_order clarifications in both functions are clear improvements over the original ambiguous phrasing.
• The sentence consolidation in resolve_matching_names_values inadvertently drops "the matched strings," so the prose now describes only two return values (indices and values) while the immediately following example tuple shows all three (indices, names, values).

Confidence Score: 3/5

The preserve_order clarifications are an improvement, but the sentence edit in resolve_matching_names_values introduces a prose/example mismatch that leaves the docstring self-contradictory.

The updated sentence omits the middle return value (names) while the example tuple immediately below still shows all three — indices, names, and values — making the documentation actively misleading.

source/isaaclab/isaaclab/utils/string.py line 293, where the example sentence now conflicts with the example tuple.

Important Files Changed

Filename	Overview
source/isaaclab/isaaclab/utils/string.py	Docstring-only changes: preserve_order descriptions improved in both functions, but the example prose for resolve_matching_names_values now omits the middle return value (names) after removing "the matched strings," from the sentence.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Input: keys / data dict + list_of_strings] --> B[Loop: match each target string against each regex key]
    B --> C{Match found?}
    C -- Yes --> D[Append to index_list, names_list, key_idx_list]
    C -- No --> B
    D --> E{preserve_order?}
    E -- False --> F[Return in target-string iteration order]
    E -- True --> G[Reorder by regex-key order]
    G --> F
    F --> H[Return tuple: indices, names, values]

Loading

_{Reviews (1): Last reviewed commit: "docs: clarify preserve_order description..." | Re-trigger Greptile}

[greptile-apps]

The edit intended to remove a redundant phrase but accidentally dropped the second return value from the prose description. The sentence now says the function returns "the indices … and the values," but the return type is a three-tuple (indices, names, values) — names (['a', 'b', 'c', 'd', 'e'] in the example) is silently omitted. Readers will see a mismatch between the prose (two things) and the immediately following example tuple (three things).

Suggested change

	If :attr:`preserve_order` is False, then the function will return the indices of the matched strings and the values as: ([0, 1, 2, 3, 4], ['a', 'b', 'c', 'd', 'e'], [1, 2, 2, 1, 1]). When
	If :attr:`preserve_order` is False, then the function will return the indices of the matched strings, the matched names, and the values as: ([0, 1, 2, 3, 4], ['a', 'b', 'c', 'd', 'e'], [1, 2, 2, 1, 1]). When