event chain documentation

src/ol/PluggableMap.js

@@ -451,7 +451,11 @@ class PluggableMap extends BaseObject {
   }
 
   /**
-   * Add the given interaction to the map.
+   * Add the given interaction to the map. If you want to add an interaction
+   * at another point of the collection use `getInteraction()` and the methods
+   * available on {@link module:ol/Collection~Collection}. This can be used to
+   * stop the event propagation from the handleEvent function. The interactions
+   * get to handle the events in the reverse order of this collection.
    * @param {import("./interaction/Interaction.js").default} interaction Interaction to add.
    * @api
    */

src/ol/interaction.js

@@ -68,8 +68,9 @@ export {default as Translate} from './interaction/Translate.js';
  * a different order for interactions, you will need to create your own
  * {@link module:ol/interaction/Interaction} instances and insert
  * them into a {@link module:ol/Collection} in the order you want
- * before creating your {@link module:ol/Map~Map} instance. The default set of
- * interactions, in sequence, is:
+ * before creating your {@link module:ol/Map~Map} instance. Changing the order can
+ * be of interest if the event propagation needs to be stopped at a point.
+ * The default set of interactions, in sequence, is:
  * * {@link module:ol/interaction/DragRotate~DragRotate}
  * * {@link module:ol/interaction/DoubleClickZoom~DoubleClickZoom}
  * * {@link module:ol/interaction/DragPan~DragPan}

src/ol/interaction/Interaction.js

@@ -14,7 +14,8 @@ import {clamp} from '../math.js';
  * Method called by the map to notify the interaction that a browser event was
  * dispatched to the map. If the function returns a falsy value, propagation of
  * the event to other interactions in the map's interactions chain will be
- * prevented (this includes functions with no explicit return).
+ * prevented (this includes functions with no explicit return). The interactions
+ * are traversed in reverse order of the interactions collection of the map.
  */