From 90c25012b9b39f53257ab3fbce059bc9414b2d66 Mon Sep 17 00:00:00 2001
From: Simon Seyock <seyock@terrestris.de>
Date: Tue, 5 Jan 2021 09:32:16 +0100
Subject: [PATCH] Improved documentation for feature load events.

---
 src/ol/featureloader.js | 10 ++++++----
 src/ol/source/Vector.js | 11 +++++++----
 2 files changed, 13 insertions(+), 8 deletions(-)

diff --git a/src/ol/featureloader.js b/src/ol/featureloader.js
index 6247be210d..e2d599832e 100644
--- a/src/ol/featureloader.js
+++ b/src/ol/featureloader.js
@@ -15,10 +15,12 @@ let withCredentials = false;
  * {@link module:ol/source/Vector} sources use a function of this type to
  * load features.
  *
- * This function takes an {@link module:ol/extent~Extent} representing the area to be loaded,
- * a `{number}` representing the resolution (map units per pixel), an
- * {@link module:ol/proj/Projection} for the projection and success and failure callbacks as
- * arguments. `this` within the function is bound to the
+ * This function takes up to 5 arguments. These are an {@link module:ol/extent~Extent} representing
+ * the area to be loaded, a `{number}` representing the resolution (map units per pixel), an
+ * {@link module:ol/proj/Projection} for the projection, an optional success callback that should get
+ * the loaded features passed as an argument and an optional failure callback with no arguments. If
+ * the callbacks are not used, the corresponding vector source will not fire `'featuresloadstart'`,
+ * `'featuresloadend'` and `'featuresloaderror'` events. `this` within the function is bound to the
  * {@link module:ol/source/Vector} it's called from.
  *
  * The function is responsible for loading the features and adding them to the
diff --git a/src/ol/source/Vector.js b/src/ol/source/Vector.js
index 1c36c542a6..83c19a54ff 100644
--- a/src/ol/source/Vector.js
+++ b/src/ol/source/Vector.js
@@ -72,7 +72,8 @@ export class VectorSourceEvent extends Event {
  * @property {import("../featureloader.js").FeatureLoader} [loader]
  * The loader function used to load features, from a remote source for example.
  * If this is not set and `url` is set, the source will create and use an XHR
- * feature loader.
+ * feature loader. The `'featuresloadstart'`, `'featuresloadend'` and `'featuresloaderror'` events
+ * will only fire if the `success` and `failure` callbacks are used.
  *
  * Example:
  *
@@ -83,7 +84,7 @@ export class VectorSourceEvent extends Event {
  *
  * var vectorSource = new Vector({
  *   format: new GeoJSON(),
- *   loader: function(extent, resolution, projection) {
+ *   loader: function(extent, resolution, projection, success, failure) {
  *      var proj = projection.getCode();
  *      var url = 'https://ahocevar.com/geoserver/wfs?service=WFS&' +
  *          'version=1.1.0&request=GetFeature&typename=osm:water_areas&' +
@@ -93,12 +94,14 @@ export class VectorSourceEvent extends Event {
  *      xhr.open('GET', url);
  *      var onError = function() {
  *        vectorSource.removeLoadedExtent(extent);
+ *        failure();
  *      }
  *      xhr.onerror = onError;
  *      xhr.onload = function() {
  *        if (xhr.status == 200) {
- *          vectorSource.addFeatures(
- *              vectorSource.getFormat().readFeatures(xhr.responseText));
+ *          var features = vectorSource.getFormat().readFeatures(xhr.responseText);
+ *          vectorSource.addFeatures(features);
+ *          success(features);
  *        } else {
  *          onError();
  *        }