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://web.archive.org/web/20240908025132/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?

[pluknet]

Hello,

I've looked once again at the current state.
The text reflects the implementation detail for ngx_hash_find_combined() based search.
So it needs to be updated in other places such as searching server names.
This also need to include the "stream" counterpart.

Regardless, the existing wording looks like it has a logic flaw.
Personally, I read it as if the priority is applied only for the case of multiple search candidates.

Since it's hard to explain in details, and to reduces the number of review round-trips,
I have updated your branch to address all the details (including translations).
Please see if it's good for you. I intend to merge this in a couple days.