Doc gen handles arrays as required property values

[davidtheclark]

Ref mapbox/mapbox-gl-style-spec#504.

Modifies the style documentation generation code to allow for an array as the required property value. An array means that the property must have one of multiple possible values.

I tried to match the sentence-style syntax and punctuation I saw elsewhere. Here's what we end up with in a few scenarios:

"requires": [ 
  {
    "icon-text-fit": ["both", "width", "height"]
  },
],

This property is only applied to the style if iconTextFit is set to either an NSValue object containing MGLSymbolStyleLayerIconTextFitBoth, or an NSValue object containing MGLSymbolStyleLayerIconTextFitWidth, or an NSValue object containing MGLSymbolStyleLayerIconTextFitHeight. Otherwise, it is ignored.

"requires": [
  {
    "icon-text-fit": [
      "both",
      "width"
    ]
  }
],

This property is only applied to the style if iconTextFit is set to either an NSValue object containing MGLSymbolStyleLayerIconTextFitBoth or an NSValue object containing MGLSymbolStyleLayerIconTextFitWidth. Otherwise, it is ignored.

"requires": [
  {
    "icon-text-fit": "both"
  }
],

This property is only applied to the style if iconTextFit is set to an NSValue object containing MGLSymbolStyleLayerIconTextFitBoth. Otherwise, it is ignored.

(Looks like I also stripped some superfluous end-of-line whitespace.)

cc @1ec5

[mention-bot]

@davidtheclark, thanks for your PR! By analyzing this pull request, we identified @1ec5, @boundsj and @incanus to be potential reviewers.

[davidtheclark]

Modified the text based on chat feedback from @1ec5. Added semicolons between required properties and removed "either" if there are more than 2 possibilities. Now the doc for icon-text-fit-padding would look like this ...

... with 2 possible values:

This property is only applied to the style if iconImage is non-nil; and textField is non-nil; and iconTextFit is set to either an NSValue object containing MGLSymbolStyleLayerIconTextFitBoth or an NSValue object containing MGLSymbolStyleLayerIconTextFitWidth. Otherwise, it is ignored.

... with 3 possible values (the real thing):

This property is only applied to the style if iconImage is non-nil; and textField is non-nil; and iconTextFit is set to an NSValue object containing MGLSymbolStyleLayerIconTextFitBoth, an NSValue object containing MGLSymbolStyleLayerIconTextFitWidth, or an NSValue object containing MGLSymbolStyleLayerIconTextFitHeight. Otherwise, it is ignored.

[davidtheclark]

Had another idea for reducing verbosity, by cutting the repetition of "an NSValue object containing". After latest commit, here's the example output ...

... with 2 possible values:

This property is only applied to the style if iconImage is non-nil; and textField is non-nil; and iconTextFit is set to an NSValue object containing either MGLSymbolStyleLayerIconTextFitBoth or MGLSymbolStyleLayerIconTextFitHeight. Otherwise, it is ignored.

... with 3 possible values:

This property is only applied to the style if iconImage is non-nil; and textField is non-nil; and iconTextFit is set to an NSValue object containing MGLSymbolStyleLayerIconTextFitBoth, MGLSymbolStyleLayerIconTextFitWidth, or MGLSymbolStyleLayerIconTextFitHeight. Otherwise, it is ignored.

[1ec5]

This is tricky stuff, but it looks pretty good! You'll need to run make style-code-darwin again to regenerate the headers.

[1ec5]

This semicolon might be excessive if none of the requirements includes a comma.

[davidtheclark]

I can remove that.

[1ec5]

Oh, a semicolon is definitely helpful if a requirement does include a comma, though. It isn’t wrong either way, since you’ve simplified the verbiage a bit, just a stylistic choice.

[davidtheclark]

@1ec5 I reverted the semicolon to a comma and rebased & squashed into a single commit.

There is and should be no changes to the generated documentation yet — not until the a new spec version is released with the change discussed in mapbox/mapbox-gl-style-spec#504.

[1ec5]

Oh, one more thing: if you don’t mind rebasing again, can you prepend [ios, macos] to the commit message? Thanks!

[friedbunny]

(Or you could add that to the commit message when you squash merge.)

[1ec5]

There is and should be no changes to the generated documentation yet — not until the a new spec version is released with the change discussed in mapbox/mapbox-gl-style-spec#504.

We update the gl-native project frequently between official specification releases, so the corresponding changes are being handled in #6508.