From b5196a65a1cac99386f711c0a8de16de3df29435 Mon Sep 17 00:00:00 2001
From: mike-000 <49240900+mike-000@users.noreply.github.com>
Date: Fri, 14 Jan 2022 12:17:08 +0000
Subject: [PATCH] Describe use of className with declutter

---
 src/ol/layer/BaseVector.js   | 5 +++++
 src/ol/layer/MapboxVector.js | 5 +++++
 src/ol/layer/VectorTile.js   | 5 +++++
 3 files changed, 15 insertions(+)

diff --git a/src/ol/layer/BaseVector.js b/src/ol/layer/BaseVector.js
index 8b8e790abf..682fc2dfd3 100644
--- a/src/ol/layer/BaseVector.js
+++ b/src/ol/layer/BaseVector.js
@@ -45,6 +45,11 @@ import {
  * is defined by the z-index of the layer, the `zIndex` of the style and the render order of features.
  * Higher z-index means higher priority. Within the same z-index, a feature rendered before another has
  * higher priority.
+ *
+ * As an optimization decluttered features from layers with the same `className` are rendered above
+ * the fill and stroke styles of all of those layers regardless of z-index.  To opt out of this
+ * behavior and place declutterd features with their own layer configure the layer with a `className`
+ * other than `ol-layer`.
  * @property {import("../style/Style.js").StyleLike|null} [style] Layer style. When set to `null`, only
  * features that have their own style will be rendered. See {@link module:ol/style/Style~Style} for the default style
  * which will be used if this is not set.
diff --git a/src/ol/layer/MapboxVector.js b/src/ol/layer/MapboxVector.js
index 73910c2a7b..324d2c079e 100644
--- a/src/ol/layer/MapboxVector.js
+++ b/src/ol/layer/MapboxVector.js
@@ -182,6 +182,11 @@ const SourceType = {
  * is defined by the z-index of the layer, the `zIndex` of the style and the render order of features.
  * Higher z-index means higher priority. Within the same z-index, a feature rendered before another has
  * higher priority.
+ *
+ * As an optimization decluttered features from layers with the same `className` are rendered above
+ * the fill and stroke styles of all of those layers regardless of z-index.  To opt out of this
+ * behavior and place declutterd features with their own layer configure the layer with a `className`
+ * other than `ol-layer`.
  * @property {import("./Base.js").BackgroundColor|false} [background] Background color for the layer.
  * If not specified, the background from the Mapbox style object will be used. Set to `false` to prevent
  * the Mapbox style's background from being used.
diff --git a/src/ol/layer/VectorTile.js b/src/ol/layer/VectorTile.js
index 4870b02614..71ef266ad7 100644
--- a/src/ol/layer/VectorTile.js
+++ b/src/ol/layer/VectorTile.js
@@ -62,6 +62,11 @@ import {assign} from '../obj.js';
  * is defined by the z-index of the layer, the `zIndex` of the style and the render order of features.
  * Higher z-index means higher priority. Within the same z-index, a feature rendered before another has
  * higher priority.
+ *
+ * As an optimization decluttered features from layers with the same `className` are rendered above
+ * the fill and stroke styles of all of those layers regardless of z-index.  To opt out of this
+ * behavior and place declutterd features with their own layer configure the layer with a `className`
+ * other than `ol-layer`.
  * @property {import("../style/Style.js").StyleLike|null} [style] Layer style. When set to `null`, only
  * features that have their own style will be rendered. See {@link module:ol/style/Style~Style} for the default style
  * which will be used if this is not set.