Document how to avoid canvas reuse for layers

This restores the `map.forEachLayerAtPixel` functionality.

This is intended to help with openlayers#9720

src/ol/PluggableMap.js

@@ -595,6 +595,10 @@ class PluggableMap extends BaseObject {
    * Detect layers that have a color value at a pixel on the viewport, and
    * execute a callback with each matching layer. Layers included in the
    * detection can be configured through `opt_layerFilter`.
+   *
+   * Note: this may give false positives unless the map layers have had different `className`
+   * properties assigned to them.
+   *
    * @param {import("./pixel.js").Pixel} pixel Pixel.
    * @param {function(this: S, import("./layer/Layer.js").default, (Uint8ClampedArray|Uint8Array)): T} callback
    *     Layer callback. This callback will receive two arguments: first is the

src/ol/layer/Layer.js

@@ -35,6 +35,7 @@ import SourceState from '../source/State.js';
  * @property {import("../PluggableMap.js").default} [map] Map.
  * @property {RenderFunction} [render] Render function. Takes the frame state as input and is expected to return an
  * HTML element. Will overwrite the default rendering for the layer.
+ * @property {string} [className='ol-layer'] A CSS class name to set to the layer element.
  */
 
 
@@ -71,6 +72,11 @@ import SourceState from '../source/State.js';
  *
  * A generic `change` event is fired when the state of the source changes.
  *
+ * Please note that for performance reasons several layers might get rendered to
+ * the same HTML element, which will cause {@link module:ol/Map~Map#forEachLayerAtPixel} to
+ * give false positives. To avoid this, apply different `className` properties to the
+ * layers at creation time.
+ *
  * @fires import("../render/Event.js").RenderEvent#prerender
  * @fires import("../render/Event.js").RenderEvent#postrender
  *