diff --git a/platform/darwin/scripts/generate-style-code.js b/platform/darwin/scripts/generate-style-code.js
index 9b164f2f4..ab0513d33 100755
--- a/platform/darwin/scripts/generate-style-code.js
+++ b/platform/darwin/scripts/generate-style-code.js
@@ -327,6 +327,9 @@ global.propertyDoc = function (propertyName, property, layerType, kind) {
     let doc = property.doc.replace(/`([^`]+?)` is set to `([^`]+?)`(?: or `([^`]+?)`)?/g, function (m, peerPropertyName, propertyValue, secondPropertyValue, offset, str) {
         let otherProperty = camelizeWithLeadingLowercase(peerPropertyName);
         let otherValue = objCType(layerType, peerPropertyName) + camelize(propertyValue);
+        if (propertyValue === 'true' || propertyValue === 'false') {
+            otherValue = propertyValue === 'true' ? 'YES' : 'NO';
+        }
         if (property.type == 'array' && kind == 'light') {
             otherValue = propertyValue;
         }
diff --git a/platform/darwin/src/MGLSymbolStyleLayer.h b/platform/darwin/src/MGLSymbolStyleLayer.h
index 712ed55b8..f5e2b490d 100644
--- a/platform/darwin/src/MGLSymbolStyleLayer.h
+++ b/platform/darwin/src/MGLSymbolStyleLayer.h
@@ -1057,10 +1057,12 @@ MGL_EXPORT
 @property (nonatomic, null_resettable) NSExpression *symbolPlacement;
 
 /**
- Sorts features in ascending order based on this value. Features with a higher
- sort key will appear above features with a lower sort key when they overlap.
- Features with a lower sort key will have priority over other features when
- doing placement.
+ Sorts features in ascending order based on this value. Features with lower sort
+ keys are drawn and placed first.  When `iconAllowsOverlap` or
+ `textAllowsOverlap` is `false`, features with a lower sort key will have
+ priority during placement. When `iconAllowsOverlap` or `textAllowsOverlap` is
+ set to `YES`, features with a higher sort key will overlap over features with a
+ lower sort key.
  
  You can set this property to an expression containing any of the following: