Improving expression syntax documentation

[sruenwg]

As a casual user of maplibre-gl, I've found myself almost always skipping over the expression documentation's syntax section when trying to figure out how to properly structure expressions (i.e. when trying to figure out the syntax).
This is mainly because:

• quite a few of the syntaxes contain mistakes, and
• there is often a lack of clarity in and information conveyed by the syntax.

I would like to use this thread to discuss solutions to this latter point, as the former is simply an accuracy issue and is partially dependent on the latter.

TLDR: I believe the expression syntax documentation is not as useful as it should or could be, and I would like to discuss ways to resolve this through establishing patterns for documenting what is currently unclear in / missing from the syntax section.

Issues

My pain points regarding syntax clarity/informativeness largely fall under two categories.

1. Use of the value type

My understanding is that value currently serves several uses depending on where it appears.

• to represent the union of all possible expression input/result types (essentially an any), e.g. as inputs to assertion expressions like ["string", value, fallback: value, fallback: value, ...]: string in place of something like ["string", any, fallback: any, fallback: any, ...]: string
• to avoid having to express generic type relations, e.g. ["at", number, value]: value in place of something like ["at", number, array<T>]: T
• to avoid having to list multiple syntaxes, e.g. ["in", value, value]: boolean in place of something like ["in", T, array<T>]: boolean and ["in", string, string]: boolean
• to avoid having to denote alternating parameter types, e.g. ["case", value, value, ..., fallback: value]: value in place of something like ["case", boolean, any, boolean, any, ..., fallback: any]: any

I have found it very confusing to have this jumble of concerns all rolled up into a single value type, so I would like a solution which splits these uses into clearly distinct patterns in the syntax.

2. Non-descriptive parameters

While the expression description currently pretty much always explains the type and function of the expression's parameters, the syntax often does not make it clear where each of these described parameters should be positioned.

The best (worst) examples of this are complex expressions containing multiple parameters of the same type, e.g. match:

match's description clearly indicates to the user that the expression accepts an 'input', 'output's, 'label's corresponding to those outputs, and a 'fallback', but the syntax only lists values — it fails to indicate which of these values corresponds to which of the aforementioned arguments.

My expectation as a user is for the syntax to help guide me in placing the arguments in the right positions for the expression to produce the result I desire, not just for it to satisfy type-checking.
I thus disagree with this decision to include only types in the syntax, and I instead agree with the sentiment behind #833 and #1065 that parameter names would help the syntax be more usable.
For example, I feel the OpenLayers expression documentation — because its syntax lists descriptive names rather than types — is much more effective at giving me a quick idea of where each argument should go in the expression: ['match', input, match1, output1, ...matchN, outputN, fallback].

Solution

Criteria

Based on the above, I would argue that the syntax documentation should satisfy the following.

1. Must have distinct syntax patterns for each of the cases listed in issue 1
   • Should have zero remaining uses of types like value which are undescriptive and serve multiple functions
2. Must make it obvious where any parameters mentioned in the description should be placed within the expression
   • In effect, the description and syntax combined should give the user enough information to construct a well-formed expression

Ideas

I would be in favour of updating the syntax section to something like the examples below.

---

Syntax:

["match", input, label1, output1, fallback]: any
["match", input, label1, output1, ..., labelN, outputN, fallback]: any

• input: any — Any expression, e.g. ["get", "building_type"].
• labelI: string literal | array<string literal> | array<number literal> — The i-th literal value or array of literal values to match the input against.
• outputI: any — The expression result when the i-th label is the first label to match the input.

---

Syntax:

["in", item, array]: boolean
["in", substring, string]: boolean

• item: T — The needle to search for within array.
• array: array<T> — The haystack through which to search for item.
• substring: string — The needle to search for within string.
• string: string — The haystack through which to search for substring.

---

1. How this meets criteria 1:
   • any makes sense to me as a suitable replacement for value where any type can be expected (see match). If necessary, I could make a note in the page's 'Type system' section to describe what any means.
   • I use T here for generics (see in) under the assumption that most users would be familiar with this syntax or could infer what it means. I am unaware of a better way to accomplish this.
   • Expressions with multiple syntaxes are simply listed on separate lines within the same syntax code block (see in). This pattern could also be useful to clearly show the minimum parameters needed in a variadic expression (see match).
   • Alternating parameter types are made clear by using descriptive names in the code block and denoting their type in the parameters list below (see match).
2. How this meets criteria 2:
   • Parameter names are simply copied from the expression description, leaving little room for ambiguity. Sensible parameter names would have to be chosen where expression descriptions do not give names to the parameters, but this should be something that can be incrementally improved.
   • Parameter types are in a separate section to avoid cluttering the syntax code block too much. I feel this design offers the best balance between informativeness and ease of reading. While this takes more vertical space than sticking both the name and type into the syntax code block, I prefer this design as it also gives more flexibility to document parameter-specific details when necessary.

These are just ideas — I would love to hear feedback on whether this looks like a good solution and/or what might work better.

---

Apologies for the long message.
I would really appreciate any input on the topic since I'm just one data point — I'd hate to implement changes that end up not being beneficial to others.

Thanks.

[HarelM]

I don't have a lot to add here, I think the description, problem statement and solution are good.
If you want to champion this please go ahead.
My main concern with previous PRs to improve on this was that they were specific and didn't create a consistent user experience when reading the docs and solved only a handful of cases and didn't take a stab at the greater picture and problem.

My second concern/request is to make sure everything is defined in v8 file and generation of documentation can be made easily with the current script and that information isn't split between multiple files.

[sruenwg]

Thank you so much for the feedback!
Yes, I'd like to start implementing this very soon, but I'd also like to leave this discussion up for a week or so in case others could pitch in.

1. didn't create a consistent user experience when reading the docs

   This makes a lot of sense, thank you for clarifying.

2. When writing the original post I did take a look at how the docs were generated, and if I understand correctly, I am thinking I would only really need to tweak the expression section in v8.json and generate-docs.ts — I will try to ensure not much else would change.

[HarelM]

Cool, thanks!