Add function and interpolation mode to style property docs #7958

boundsj · 2017-02-06T23:14:27Z

This adds documentation to each style layer property that specifies the function and interpolation mode combinations that will work for the property.

In some cases, function and interpolation stop combination values that don't make sense will be coerced into a values that do. For example, a camera function with and exponential interpolation mode that is set on a property that is a piecewise-constant function will be converted into a camera function with an interval interpolation mode.

mention-bot · 2017-02-06T23:14:30Z

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

1ec5 · 2017-02-07T01:00:02Z

platform/darwin/scripts/generate-style-code.js

+ 'interpolation mode, an `MGLSourceStyleFunction` using an `MGLInterpolationModeExponential`, `MGLInterpolationModeInterval`, `MGLInterpolationModeCategorical, or `MGLInterpolationModeIdentity` ' + 
+ 'interpolation mode, or an `MGLCompositeStyleFunction` using an `MGLInterpolationModeExponential`, `MGLInterpolationModeInterval` or `MGLInterpolationModeCategorical` interpolation mode`';
+ } else {
+ if (property.function == "interpolated") {


Nit: use the === operator unless type coercion is required.

1ec5 · 2017-02-07T01:00:14Z

platform/darwin/scripts/generate-style-code.js

+ doc += '`\n\nThis property can be set to an `MGLStyleConstantValue` or an `MGLCameraStyleFunction` using an `MGLInterpolationModeExponential` or `MGLInterpolationModeInterval` ' +
+ 'interpolation mode';
+ } else {
+ doc += '`\n\nThis property can be set to an `MGLStyleConstantValue` or an `MGLCameraStyleFunction` using an `MGLInterpolationModeInterval` interpolation mode';


Funky indentation.

1ec5 · 2017-02-07T01:01:09Z

platform/darwin/scripts/generate-style-code.js

+ if (property["property-function"]) {
+ doc += '`\n\nThis property can be set to an `MGLStyleConstantValue`, an `MGLCameraStyleFunction` using an `MGLInterpolationModeExponential` or `MGLInterpolationModeInterval` ' +
+ 'interpolation mode, an `MGLSourceStyleFunction` using an `MGLInterpolationModeExponential`, `MGLInterpolationModeInterval`, `MGLInterpolationModeCategorical, or `MGLInterpolationModeIdentity` ' + 
+ 'interpolation mode, or an `MGLCompositeStyleFunction` using an `MGLInterpolationModeExponential`, `MGLInterpolationModeInterval` or `MGLInterpolationModeCategorical` interpolation mode`';


End this sentence with a period.

friedbunny

Concatenating strings is leading to long, difficult to follow sentences — could we organize these into tables or otherwise section them?

friedbunny · 2017-02-08T19:01:16Z

platform/darwin/scripts/generate-style-code.js

+ if (property["property-function"]) {
+ doc += '`\n\nThis property can be set to an `MGLStyleConstantValue`, an `MGLCameraStyleFunction` using an `MGLInterpolationModeExponential` or `MGLInterpolationModeInterval` ' +
+ 'interpolation mode, an `MGLSourceStyleFunction` using an `MGLInterpolationModeExponential`, `MGLInterpolationModeInterval`, `MGLInterpolationModeCategorical, or `MGLInterpolationModeIdentity` ' + 
+ 'interpolation mode, or an `MGLCompositeStyleFunction` using an `MGLInterpolationModeExponential`, `MGLInterpolationModeInterval` or `MGLInterpolationModeCategorical` interpolation mode`.';


The end of this string has a stray tick before the period.

Which leads to this, on MGLCircleStyleLayer.circleOpacity:

1ec5 · 2017-02-08T19:26:48Z

Concatenating strings is leading to long, difficult to follow sentences — could we organize these into tables or otherwise section them?

Yes. At the very least, we should use semicolons to separate list items that contain commas.

boundsj · 2017-02-08T20:14:44Z

@friedbunny @1ec5 I did not find markup for creating arbitrary tables in jazzy. Are the changes in a749e82 suitable? Example:

friedbunny · 2017-02-08T22:38:36Z

That looks much better, thanks @boundsj. For tables in jazzy, we’ve been resorting to HTML (but that tends to look terrible inline).

friedbunny · 2017-02-08T23:02:07Z

Pushed 9ae227e, which adds even more bullets:

incanus · 2017-02-08T23:15:47Z

even more bullets

1ec5 · 2017-02-08T23:48:20Z

For tables in jazzy, we’ve been resorting to HTML (but that tends to look terrible inline).

We also have some instances of Markdown tables in the jazzy guides, but we only get away with that because the guides don’t appear in Quick Help or any headers.

boundsj · 2017-02-08T23:49:54Z

I'm liking the even more bullets look anyway.

1ec5 · 2017-02-08T23:50:43Z

platform/darwin/scripts/generate-style-code.js

@@ -281,6 +281,30 @@ global.propertyDoc = function (propertyName, property, layerType, kind) {
 doc += `\n\nThis attribute corresponds to the <a href="https://www.mapbox.com/mapbox-gl-style-spec/#${anchor}"><code>${property.original}</code></a> layout property in the Mapbox Style Specification.`;
 }
 }
+ doc += '\n\nThis property can be set to one of the following values:\n\n' +


We’re saying what kind of values the property can be set to, not which values specifically. Also, avoid passive voice:

You can set this property to an instance of:

Fixed in c602839

1ec5 · 2017-02-08T23:51:13Z

platform/darwin/scripts/generate-style-code.js

+ doc += '\n\nThis property can be set to one of the following values:\n\n' +
+ '- `MGLStyleConstantValue`\n';
+ if (property["property-function"]) {
+ doc += '- `MGLCameraStyleFunction` with an interpolation mode of:\n' +


FYI, we’ve been using * syntax in other places, but I don’t think it matters much.

Updated in c602839 for consistency

1ec5 · 2017-02-08T23:52:39Z

platform/darwin/src/MGLCircleStyleLayer.h

@@ -9,34 +9,70 @@ NS_ASSUME_NONNULL_BEGIN

 /**
 Controls the scaling behavior of the circle when the map is pitched.
+
+ This property can be set to one of the following values:


This isn’t a property, it’s an enumeration value. Enumeration values don’t need this extra text.

Thanks for catching this! Updated in c602839

1ec5

Looks good! Before merging, please make sure the various regular expressions in make darwin-update-examples (or make style-code, which depends on it) can cope with the new documentation, just in case.

boundsj added documentation GL JS parity For feature parity with Mapbox GL JS iOS Mapbox Maps SDK for iOS macOS Mapbox Maps SDK for macOS runtime styling labels Feb 6, 2017

boundsj added this to the ios-v3.5.0 milestone Feb 6, 2017

boundsj self-assigned this Feb 6, 2017

boundsj requested a review from 1ec5 February 6, 2017 23:14

1ec5 reviewed Feb 7, 2017

View reviewed changes

friedbunny suggested changes Feb 8, 2017

View reviewed changes

boundsj mentioned this pull request Feb 8, 2017

Add documentation for data-driven styling #7924

Closed

18 tasks

friedbunny approved these changes Feb 8, 2017

View reviewed changes

1ec5 suggested changes Feb 8, 2017

View reviewed changes

boundsj and others added 3 commits February 8, 2017 16:08

[ios, macos] Add function and interpolation mode to style property docs

d4cf5ee

[ios, macos] Add more bullets to style property docs

77dce27

[ios, macos] Don't add documentation to NS_ENUM

c602839

boundsj force-pushed the boundsj-document-interpolation-mode branch from 9ae227e to c602839 Compare February 9, 2017 00:27

1ec5 approved these changes Feb 9, 2017

View reviewed changes

boundsj merged commit a49301a into master Feb 9, 2017

boundsj deleted the boundsj-document-interpolation-mode branch February 9, 2017 05:11

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add function and interpolation mode to style property docs #7958

Add function and interpolation mode to style property docs #7958

boundsj commented Feb 6, 2017

mention-bot commented Feb 6, 2017

1ec5 Feb 7, 2017

1ec5 Feb 7, 2017

1ec5 Feb 7, 2017

friedbunny left a comment

friedbunny Feb 8, 2017

friedbunny Feb 8, 2017

1ec5 commented Feb 8, 2017

boundsj commented Feb 8, 2017

friedbunny commented Feb 8, 2017

friedbunny commented Feb 8, 2017

incanus commented Feb 8, 2017

1ec5 commented Feb 8, 2017

boundsj commented Feb 8, 2017

1ec5 Feb 8, 2017

boundsj Feb 9, 2017

1ec5 Feb 8, 2017

boundsj Feb 9, 2017

1ec5 Feb 8, 2017

boundsj Feb 9, 2017

1ec5 left a comment

Add function and interpolation mode to style property docs #7958

Add function and interpolation mode to style property docs #7958

Conversation

boundsj commented Feb 6, 2017

mention-bot commented Feb 6, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

friedbunny left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

1ec5 commented Feb 8, 2017

boundsj commented Feb 8, 2017

friedbunny commented Feb 8, 2017

friedbunny commented Feb 8, 2017

incanus commented Feb 8, 2017

1ec5 commented Feb 8, 2017

boundsj commented Feb 8, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

1ec5 left a comment

Choose a reason for hiding this comment