Document "in" expression

[stevage]

The new "in" operator (#8876) somehow missed getting documented.

Note the word "deprecated" can be removed from this sentence about match:

similar to the deprecated "in" operator.

Also, it seems to me that with this inclusion, everything that was possible with the old filter syntax is now easily possible with expressions, simply by replacing key with ["get", key]. (Except "none" which is just ["!", ["any", ...]]

So it might be time to finally completely remove the deprecated filter syntax documentation. It's much safer in general to avoid ever using it, so you don't fall into weird traps when you try to do things that it doesn't support.

[ryanhamley]

The deprecated "in" operator was fixed in #9102 but it appears that it was never included in a style spec release so the docs weren't updated.

The in operator was also documented in the PR that implemented it but it's not showing up in the docs. Clearly there are some issues to be worked out with updating the docs now that they're split into a separate repo.

I'm not sure about completely removing the filter syntax from the docs since it's still valid, but we do need to update it to remove references to the in filter as documented in https://github.com/mapbox/mapbox-gl-js-docs/issues/199. It might be worth making it more explicit in the docs that the filter syntax is deprecated in favor of expressions.

[stevage]

Ah, yes, makes sense, sorry.

I'm not sure about completely removing the filter syntax from the docs since it's still valid,

My other reason for suggesting this is that navigating the docs is harder when there are multiple sets of things with the same name. I don't know about other people, but my main method to look up a definition is to do a find within the page, say for "in" (with the quotes). I have to be really careful to check that the definition that it lands on is not the deprecated syntax.

I sort of understand the desire to keep documentation around to help people who are coming across existing code. But if this syntax is truly "deprecated" then surely we don't want anyone writing it anymore, in order that it can be completely removed from mapbox-gl at some point in the future. So maybe moving it out of the main documentation to some other dumping ground might be a step on that journey :)

[ryanhamley]

I'm working on updating the docs so that the in operator shows up and the deprecated reference is removed. I'll try to get those changes into our release next week.

I understand your rationale for removing the filter syntax entirely. I'm all for removing dead weight whenever possible. We still get a significant number of questions and issues about filter syntax however, so I worry that it's too widely used for us to remove it from the docs. It would definitely need to be a team decision. Would you want to open a separate issue explicitly about this and we can tag it with needs discussion?

In the meantime, I'll also remove references to the in filter to remove that ambiguity.

[ryanhamley]

Capturing here that the style spec docs were significantly redesigned and launched just within the last day. The new design clearly marks the filter syntax as Legacy and breaks the expression docs and filter docs into separate pages which makes searching for operator names easier. I'm not going to change the filter docs at this time.

[ryanhamley]

Closed via https://github.com/mapbox/mapbox-gl-js-docs/pull/202

The in expression will show up in the docs now and the reference to the deprecated "in" operator in the match docs will be removed when docs is updated with the newest GL JS release, probably next week sometime.