From 53239f7b1e1b9a60e0dda832ef2a8a5294d97142 Mon Sep 17 00:00:00 2001
From: Andreas Hocevar <andreas.hocevar@gmail.com>
Date: Sat, 12 Feb 2022 12:57:19 +0100
Subject: [PATCH] Document difference between Vector and VectorImage layers

---
 config/jsdoc/api/index.md   | 1 +
 src/ol/layer/Vector.js      | 6 +++++-
 src/ol/layer/VectorImage.js | 6 +++++-
 3 files changed, 11 insertions(+), 2 deletions(-)

diff --git a/config/jsdoc/api/index.md b/config/jsdoc/api/index.md
index 22e7043176..7f8855863b 100644
--- a/config/jsdoc/api/index.md
+++ b/config/jsdoc/api/index.md
@@ -27,6 +27,7 @@
         <a href="module-ol_layer_Tile-TileLayer.html">ol/layer/Tile</a><br>
         <a href="module-ol_layer_Image-ImageLayer.html">ol/layer/Image</a><br>
         <a href="module-ol_layer_Vector-VectorLayer.html">ol/layer/Vector</a><br>
+        <a href="module-ol_layer_VectorImage-VectorImageLayer.html">ol/layer/VectorImage</a><br>
         <a href="module-ol_layer_VectorTile-VectorTileLayer.html">ol/layer/VectorTile</a><br>
         <a href="module-ol_layer_WebGLTile-WebGLTileLayer.html">ol/layer/WebGLTile</a>
       </div>
diff --git a/src/ol/layer/Vector.js b/src/ol/layer/Vector.js
index 0bc6fbc71c..c2c2001ebf 100644
--- a/src/ol/layer/Vector.js
+++ b/src/ol/layer/Vector.js
@@ -6,7 +6,11 @@ import CanvasVectorLayerRenderer from '../renderer/canvas/VectorLayer.js';
 
 /**
  * @classdesc
- * Vector data that is rendered client-side.
+ * Vector data is rendered client-side, as vectors. This layer type provides most accurate rendering
+ * even during animations. Points and labels stay upright on rotated views. For very large
+ * amounts of vector data, performance may suffer during pan and zoom animations. In this case,
+ * try {@link module:ol/layer/VectorImage~VectorImageLayer}.
+ *
  * Note that any property set in the options is set as a {@link module:ol/Object~BaseObject}
  * property on the layer object; for example, setting `title: 'My Title'` in the
  * options means that `title` is observable, and has get/set accessors.
diff --git a/src/ol/layer/VectorImage.js b/src/ol/layer/VectorImage.js
index 30821f006f..3487562c52 100644
--- a/src/ol/layer/VectorImage.js
+++ b/src/ol/layer/VectorImage.js
@@ -49,7 +49,11 @@ import {assign} from '../obj.js';
 
 /**
  * @classdesc
- * Vector data that is rendered client-side.
+ * Vector data is rendered client-side, to an image. This layer type provides great performance
+ * during panning and zooming, but point symbols and texts are always rotated with the view and
+ * pixels are scaled during zoom animations. For more accurate rendering of vector data, use
+ * {@link module:ol/layer/Vector~VectorLayer} instead.
+ *
  * Note that any property set in the options is set as a {@link module:ol/Object~BaseObject}
  * property on the layer object; for example, setting `title: 'My Title'` in the
  * options means that `title` is observable, and has get/set accessors.