Improved docs on map matching.

[nisbet-hubbard]

This PR improves the wording regarding map testing to reflect the performance benefits of using exact match over regex.

https://forum.nginx.org/read.php?2,214693,214694

[y82]

Hi @nisbet-hubbard,

Thank you for your contribution and for your attention to detail. I still find the existing phrasing — “regular expression match” and “matching variant chosen” — quite clear and consistent with our current terminology. Additionally, we haven’t previously used the term “testing” in this context, while phrases like “strings evaluated/matched” and “regular expressions matched” are more established.

This is just my perspective, and other community members may have different thoughts on this.

[nisbet-hubbard]

Thanks! I’ve updated the patch to address these concerns.

What bothers me in the original version is that wording like ‘If the source value matches more than one of the specified variants’ doesn’t make it clear (to people who are not already familiar with the codebase) whether all the variants are actually searched or just the variants up to the first match. So, I’m borrowing a phrase from the docs on the location directive to clarify this point.

[nisbet-hubbard]

Rebased as per guidelines.

[pluknet]

In my personal reading of the current wording:
"the first matching variant will be chosen"
already implies that
"the search terminates on the first match".

Further, regarding the patch, I don't like that "the first matching" is used twice, it worsens the wording quality.

[nisbet-hubbard]

Absolutely, and it's because you already know that's what it means.

What I was trying to get across is we understand what the current wording implies on personal reading because we already know what it implies. And we need to stand in the shoes of someone who doesn't.

In any case, here's an alternative edit:

If the source value potentially matches more than one of the specified variants

Would this satisfy everyone?