Merge pull request #8470 from scroach/tile-api-doc

Update Tile loading API docs

src/ol/Tile.js

@@ -9,7 +9,36 @@ import EventType from './events/EventType.js';
 
 /**
  * A function that takes an {@link module:ol/Tile} for the tile and a
- * `{string}` for the url as arguments.
+ * `{string}` for the url as arguments. The default is
+ * ```js
+ * source.setTileLoadFunction(function(tile, src) {
+ *   tile.getImage().src = src;
+ * });
+ * ```
+ * For more fine grained control, the load function can use fetch or XMLHttpRequest and involve
+ * error handling:
+ *
+ * ```js
+ * import TileState from 'ol/TileState';
+ *
+ * source.setTileLoadFunction(function(tile, src) {
+ *   var xhr = new XMLHttpRequest();
+ *   xhr.responseType = 'blob';
+ *   xhr.addEventListener('loadend', function (evt) {
+ *     var data = this.response;
+ *     if (data !== undefined) {
+ *       tile.getImage().src = URL.createObjectURL(data);
+ *     } else {
+ *       tile.setState(TileState.ERROR);
+ *     }
+ *   });
+ *   xhr.addEventListener('error', function () {
+ *     tile.setState(TileState.ERROR);
+ *   });
+ *   xhr.open('GET', src);
+ *   xhr.send();
+ * });
+ * ```
  *
  * @typedef {function(module:ol/Tile, string)} LoadFunction
  * @api
@@ -44,7 +73,7 @@ import EventType from './events/EventType.js';
  * Base class for tiles.
  *
  * @abstract
-  */
+ */
 class Tile extends EventTarget {
 
   /**
@@ -192,7 +221,12 @@ class Tile extends EventTarget {
   }
 
   /**
+   * Sets the state of this tile. If you write your own {@link module:ol/Tile~LoadFunction tileLoadFunction} ,
+   * it is important to set the state correctly to {@link module:ol/TileState~ERROR}
+   * when the tile cannot be loaded. Otherwise the tile cannot be removed from
+   * the tile queue and will block other requests.
    * @param {module:ol/TileState} state State.
+   * @api
    */
   setState(state) {
     this.state = state;

src/ol/TileState.js

@@ -9,6 +9,11 @@ export default {
   IDLE: 0,
   LOADING: 1,
   LOADED: 2,
+  /**
+   * Indicates that tile loading failed
+   * @type {number}
+   * @api
+   */
   ERROR: 3,
   EMPTY: 4,
   ABORT: 5