Improve documentation

externs/olx.js

@@ -4334,7 +4334,9 @@ olx.layer.VectorOptions.prototype.source;
 
 
 /**
- * Declutter images and text. Default is `false`.
+ * Declutter images and text. Decluttering is applied to all image and text
+ * styles, and the priority is defined by the z-index of the style. Higher
+ * z-index means higher priority. Default is `false`.
  * @type {boolean|undefined}
  * @api
  */
@@ -4510,7 +4512,10 @@ olx.layer.VectorTileOptions.prototype.source;
 
 
 /**
- * Declutter images and text. Default is `false`.
+ * Declutter images and text. Decluttering is applied to all image and text
+ * styles, and the priority is defined by the z-index of the style. Higher
+ * z-index means higher priority. When set to `true`, a `renderMode` of
+ * `'image'` will be overridden with `'hybrid'`. Default is `false`.
  * @type {boolean|undefined}
  * @api
  */

src/ol/render/canvas/imagereplay.js

@@ -23,7 +23,7 @@ ol.render.canvas.ImageReplay = function(
 
   /**
    * @private
-   * @type {Array.<*>}
+   * @type {ol.DeclutterGroup}
    */
   this.declutterGroup_ = null;
 
@@ -220,7 +220,7 @@ ol.render.canvas.ImageReplay.prototype.setImageStyle = function(imageStyle, decl
   var origin = imageStyle.getOrigin();
   this.anchorX_ = anchor[0];
   this.anchorY_ = anchor[1];
-  this.declutterGroup_ = /** @type {Array.<*>} */ (declutterGroup);
+  this.declutterGroup_ = /** @type {ol.DeclutterGroup} */ (declutterGroup);
   this.hitDetectionImage_ = hitDetectionImage;
   this.image_ = image;
   this.height_ = size[1];

src/ol/render/canvas/replay.js

@@ -156,7 +156,7 @@ ol.inherits(ol.render.canvas.Replay, ol.render.VectorContext);
  * @param {HTMLImageElement|HTMLCanvasElement|HTMLVideoElement} image Image.
  * @param {number} anchorX Anchor X.
  * @param {number} anchorY Anchor Y.
- * @param {Array.<*>} declutterGroup Declutter group.
+ * @param {ol.DeclutterGroup} declutterGroup Declutter group.
  * @param {number} height Height.
  * @param {number} opacity Opacity.
  * @param {number} originX Origin X.
@@ -383,7 +383,7 @@ ol.render.canvas.Replay.prototype.fill_ = function(context, rotation) {
 
 
 /**
- * @param {Array.<*>} declutterGroup Declutter group.
+ * @param {ol.DeclutterGroup} declutterGroup Declutter group.
  */
 ol.render.canvas.Replay.prototype.renderDeclutter_ = function(declutterGroup) {
   if (declutterGroup && declutterGroup.length > 5) {
@@ -537,7 +537,7 @@ ol.render.canvas.Replay.prototype.replay_ = function(
         // Remaining arguments in DRAW_IMAGE are in alphabetical order
         anchorX = /** @type {number} */ (instruction[4]);
         anchorY = /** @type {number} */ (instruction[5]);
-        declutterGroup = /** @type {Array.<*>} */ (instruction[6]);
+        declutterGroup = /** @type {ol.DeclutterGroup} */ (instruction[6]);
         var height = /** @type {number} */ (instruction[7]);
         var opacity = /** @type {number} */ (instruction[8]);
         var originX = /** @type {number} */ (instruction[9]);
@@ -565,7 +565,7 @@ ol.render.canvas.Replay.prototype.replay_ = function(
         var images =  /** @type {Array.<HTMLCanvasElement>} */ (instruction[3]);
         // Remaining arguments in DRAW_CHARS are in alphabetical order
         var baseline = /** @type {number} */ (instruction[4]);
-        declutterGroup = /** @type {Array.<*>} */ (instruction[5]);
+        declutterGroup = /** @type {ol.DeclutterGroup} */ (instruction[5]);
         var exceedLength = /** @type {number} */ (instruction[6]);
         var maxAngle = /** @type {number} */ (instruction[7]);
         var measure = /** @type {function(string):number} */ (instruction[8]);

src/ol/render/canvas/replaygroup.js

@@ -41,13 +41,7 @@ ol.render.canvas.ReplayGroup = function(
   this.declutterTree_ = declutterTree;
 
   /**
-   * Container for decluttered replay instructions that need to be rendered or
+   * @type {ol.DeclutterGroup}
-   * omitted together, i.e. when styles render both an image and text. The basic
-   * elements of this array are `[minX, minY, maxX, maxY, count]`, where the
-   * first four entries are the rendered extent in pixel space. `count` is the
-   * number of replay instructions in the group. In addition to these basic
-   * elements, declutter instructions are appended to the array.
-   * @type {Array.<*>}
    * @private
    */
   this.declutterGroup_ = null;
@@ -224,7 +218,7 @@ ol.render.canvas.ReplayGroup.replayDeclutterHitDetection = function(
 
 /**
  * @param {boolean} group Group with previous replay.
- * @return {Array.<*>} Declutter instruction group.
+ * @return {ol.DeclutterGroup} Declutter instruction group.
  */
 ol.render.canvas.ReplayGroup.prototype.addDeclutter = function(group) {
   var declutter = null;
@@ -297,7 +291,8 @@ ol.render.canvas.ReplayGroup.prototype.finish = function() {
  *     to skip.
  * @param {function((ol.Feature|ol.render.Feature)): T} callback Feature
  *     callback.
- * @param {Object.<string, Array.<*>>} declutterReplays Declutter replays.
+ * @param {Object.<string, ol.DeclutterGroup>} declutterReplays Declutter
+ *     replays.
  * @return {T|undefined} Callback result.
  * @template T
  */
@@ -426,7 +421,8 @@ ol.render.canvas.ReplayGroup.prototype.isEmpty = function() {
  *     to skip.
  * @param {Array.<ol.render.ReplayType>=} opt_replayTypes Ordered replay types
  *     to replay. Default is {@link ol.render.replay.ORDER}
- * @param {Object.<string, Array.<*>>=} opt_declutterReplays Declutter replays.
+ * @param {Object.<string, ol.DeclutterGroup>=} opt_declutterReplays Declutter
+ *     replays.
  */
 ol.render.canvas.ReplayGroup.prototype.replay = function(context,
     transform, viewRotation, skippedFeaturesHash, opt_replayTypes, opt_declutterReplays) {
@@ -479,7 +475,8 @@ ol.render.canvas.ReplayGroup.prototype.replay = function(context,
  *     Feature callback.
  * @param {ol.Extent=} opt_hitExtent Only check features that intersect this
  *     extent.
- * @param {Object.<string, Array.<*>>=} opt_declutterReplays Declutter replays.
+ * @param {Object.<string, ol.DeclutterGroup>=} opt_declutterReplays Declutter
+ *     replays.
  * @return {T|undefined} Callback result.
  * @template T
  */
@@ -527,7 +524,7 @@ ol.render.canvas.ReplayGroup.prototype.replayHitDetection_ = function(
  * @private
  * @type {Object.<ol.render.ReplayType,
  *                function(new: ol.render.canvas.Replay, number, ol.Extent,
- *                number, number, boolean, Array.<Array.<*>>)>}
+ *                number, number, boolean, Array.<ol.DeclutterGroup>)>}
  */
 ol.render.canvas.ReplayGroup.BATCH_CONSTRUCTORS_ = {
   'Circle': ol.render.canvas.PolygonReplay,

src/ol/render/canvas/textreplay.js

@@ -32,7 +32,7 @@ ol.render.canvas.TextReplay = function(
 
   /**
    * @private
-   * @type {Array.<*>}
+   * @type {ol.DeclutterGroup}
    */
   this.declutterGroup_;
 
@@ -401,7 +401,7 @@ ol.render.canvas.TextReplay.prototype.drawTextImage_ = function(label, begin, en
  * @private
  * @param {number} begin Begin.
  * @param {number} end End.
- * @param {Array.<*>} declutterGroup Declutter group.
+ * @param {ol.DeclutterGroup} declutterGroup Declutter group.
  */
 ol.render.canvas.TextReplay.prototype.drawChars_ = function(begin, end, declutterGroup) {
   var pixelRatio = this.pixelRatio;
@@ -454,7 +454,7 @@ ol.render.canvas.TextReplay.prototype.setTextStyle = function(textStyle, declutt
   if (!textStyle) {
     this.text_ = '';
   } else {
-    this.declutterGroup_ = /** @type {Array.<*>} */ (declutterGroup);
+    this.declutterGroup_ = /** @type {ol.DeclutterGroup} */ (declutterGroup);
     var textFillStyle = textStyle.getFill();
     if (!textFillStyle) {
       fillState = this.textFillState_ = null;

src/ol/render/vectorcontext.js

@@ -123,13 +123,13 @@ ol.render.VectorContext.prototype.setFillStrokeStyle = function(fillStyle, strok
 
 /**
  * @param {ol.style.Image} imageStyle Image style.
- * @param {Array.<*>=} opt_declutterGroup Declutter.
+ * @param {ol.DeclutterGroup=} opt_declutterGroup Declutter.
  */
 ol.render.VectorContext.prototype.setImageStyle = function(imageStyle, opt_declutterGroup) {};
 
 
 /**
  * @param {ol.style.Text} textStyle Text style.
- * @param {Array.<*>=} opt_declutterGroup Declutter.
+ * @param {ol.DeclutterGroup=} opt_declutterGroup Declutter.
  */
 ol.render.VectorContext.prototype.setTextStyle = function(textStyle, opt_declutterGroup) {};

src/ol/typedefs.js

@@ -167,6 +167,20 @@ ol.Coordinate;
 ol.CoordinateFormatType;
 
 
+/**
+ * Container for decluttered replay instructions that need to be rendered or
+ * omitted together, i.e. when styles render both an image and text, or for the
+ * characters that form text along lines. The basic elements of this array are
+ * `[minX, minY, maxX, maxY, count]`, where the first four entries are the
+ * rendered extent of the group in pixel space. `count` is the number of styles
+ * in the group, i.e. 2 when an image and a text are grouped, or 1 otherwise.
+ * In addition to these four elements, declutter instruction arrays (i.e. the
+ * arguments to @{link ol.render.canvas.drawImage} are appended to the array.
+ * @typedef {Array.<*>}
+ */
+ol.DeclutterGroup;
+
+
 /**
  * A function that takes a {@link ol.MapBrowserEvent} and two
  * {@link ol.Pixel}s and returns a `{boolean}`. If the condition is met,