Add style-spec note on in type system hint #9373

[rreusser]

This PR addresses the comment in #9373 (comment) by adding the following note regarding the in expression:

in

Determines whether an item exists in an array or a substring exists in a string. In the specific case when the second and third arguments are string literals, you must wrap at least one of them in a literal expression to hint correct interpretation to the type system.

It took me a bit to (I hope) understand this issue correctly, but it comes down to this comment: #9374 (comment)

Expression (preferred):

["in", 
 string | number | boolean,
 string | array]

Legacy filter (fallback):

["in",
 string,
 (string | number | boolean)...]

The specific case which fails to fall through is ["in", "string", "string"]. To the best of my knowledge, all other cases are handled correctly, so that a very targeted note on this case seemed best.

Launch Checklist

• briefly describe the changes in this PR
• include before/after visuals or gifs if this PR includes visual changes
• write tests for all new functionality
• document any changes to public APIs
• post benchmark scores
• manually test the debug page
• tagged @mapbox/map-design-team @mapbox/static-apis if this PR includes style spec API or visual changes
• tagged @mapbox/gl-native if this PR includes shader changes or needs a native port
• apply changelog label ('bug', 'feature', 'docs', etc) or use the label 'skip changelog'
• add an entry inside this element for inclusion in the mapbox-gl-js changelog: <changelog></changelog>

[domlet]

Thank you @rreusser for your careful review of this issue and adding this note with the workaround.

I notice this test failing:

render-tests/terrain/error-overlap/initializing-no-terrain-at-center timed out after 5000ms - Chrome 91.0

But the note looks great to me!

[rreusser]

Thanks, @domlet! FYI test-render and test-prod perform the exact same test, just one of them against the source code and the other against the final production bundle, so if one fails and not the other, it's almost always spurious and just needs to be rereun. Have rerun via circle-ci and looks like a ✅ .

[HansBrende]

@rreusser fyi... I was very confused by this comment in the docs because it said "the second and third argument" rather than the "first and second argument". In order to understand which arguments this was referring to, I had to search for the relevant github issue. My understanding was that the in keyword itself is not an argument but an operator. In addition to that, a note on what the semantics of the legacy behavior was would have been helpful (otherwise, have no clue what the semantics of ["in", string, string] are). A simple example of this edge case in the docs would be nice.