[docs] Add distance expression entry; update other expressions

[chloekraw]

Changelog:

• distance:
  • added entry and SDK support table
• within:
  • re-organized entry to increase clarity and conciseness
• format:
  • mentioned the image expression explicitly in the documentation entry
  • re-formatted with bullet points
  • added version support information for Android SDK
• index-of:
  • reworded entry to match language of in expression
  • removed misleading usage of "second argument," which doesn't match how current docs for get and has use "second argument." Considering ["index-of", needle, haystack, fromIndex], it's the third argument that can be optionally provided to configure the start index of the search.
• slice:
  • reworded entry to match language of in expression
  • moved group from String to Lookup because slice is closer to the in and index-of expressions in function than other expressions in the String group. No other expressions in the String group work on arrays.
  • removed misleading usage of "second argument." Considering ["slice", input, startIndex, endIndex], it's the third argument that can be optionally provided to configure the end index.
• match:
  • minor nitpick to match other entries which use - instead of * for formatting bullet points
• interpolate: no changes made

cc @lbutler @zmiao @alexshalamov @1ec5

[chloekraw]

@colleenmcginnis I tried to push my branch to our staging server but it didn't work. Not sure if it's possible for this part of our documentation?

[colleenmcginnis]

@colleenmcginnis I tried to push my branch to our staging server but it didn't work. Not sure if it's possible for this part of our documentation?

It's possible, but it's not something we do often. It would require updating the submodule in /mapbox-gl-js-docs to this commit and then pushing to publisher-staging from there. As far as I know, this repo is no longer connected to publisher at all.

If you were just pushing to staging to check the formatting, that's something I (or likely someone from the GL JS team) could do as a part of a PR review. In the future we could pair on something like this, but unfortunately this week is a busy one for our team so if this is an urgent change I'd recommend asking for a reviewer to check formatting locally instead.

[asheemmamoowala]

🙇 for docs improvements

[asheemmamoowala]

Noting here that the the unit test failure is from a missing implementation:

test/unit/style-spec/expression.test.js .............. 9/10
  v8.json includes all definitions from style-spec
  not ok should be equivalent
    --- wanted
    +++ found
       "coalesce"
       "collator"
       "concat"
       "cos"
    -  "distance"
       "downcase"
       "e"
       "feature-state"
       "floor"
    at:
      line: 14
      column: 7
      file: test/unit/style-spec/expression.test.js
      type: Test

[1ec5]

Looks OK to me as far as the iOS/macOS compatibility entries.

The iOS/macOS code generation scripts try to reformat the doc strings into jazzy format (Doxygen for block-level formatting, Markdown for inline formatting, with specific formatting for symbol references). That step would be insufficient for these strings, both before and after the changes, but fortunately the NSExpression documentation is handwritten separately instead of generated from the style specification. The NSExpression documentation doesn’t go into quite as much detail about distance, but it does link to the published style specification for additional details.

[zmiao]

👍

[chloekraw]

@mapbox/gl-js I added screenshots previewing all of the expressions doc updates in the first post of this ticket. This PR pairs with this branch in mapbox-gl-js-docs.

@ryanhamley I wasn't sure about the "needle / haystack" terminology in the in expression metadata. It seems much more specific than other terms that we use -- I think when values can be multiple types we previously used generic terms like InputType and OutputType to stay away from non-generalizable details that are specific enough that they can (and do) serve as the variable names in the implementation.

It's a tough trade-off between clarity and consistency. I tried the version below first and I do think it's too messy and unclear with the multiple | and , so I'm thinking about changing it to ["in", InputType (boolean, string, or number), InputType (array or string)]. Thoughts?

[ryanhamley]

@chloekraw I think if that's what we've standardized the rest of the docs around then it's ok to make it more generic. I definitely prefer the ["in", InputType (boolean, string, or number), InputType (array or string)] formulation to be clearer about the grouping of types. I think the only concern is that it may become confusing about which argument is which. That's partially what the needle and haystack nomenclature represents, but we could think of other ways to be more explicit about this distinction. Or maybe the implicit recognition by type is sufficient. It's explicitly documented as finding a value in a string or array and only the second argument supports those types.

TLDR: I'm not married to the needle/haystack terminology. It was mostly just to clarify the order of arguments.

[chloekraw]

@ryanhamley thanks! yeah, I think that makes sense, and I do appreciate that your version is clearer about the usage. I think we can also achieve that goal through creating a GL JS example. I was trying to think of a way to add a sentence to the expression definition that could clarify the first vs. second argument, but I came up blank. I think the first argument could be described as a e.g. "search query" but I couldn't really think of a general term for the second argument. If you have a suggestion, let me know!

[chloekraw]

@asheemmamoowala @ryanhamley @ansis @1ec5 @zmiao @alexshalamov thanks for all the feedback! I'm going to merge this and cherrypick to release-danube now, but happy to revisit any of the changes in the future.