Add docs for updating ajax headers

src/tiledimage.js

@@ -1010,7 +1010,18 @@ $.extend($.TiledImage.prototype, $.EventSource.prototype, /** @lends OpenSeadrag
     },
 
     /**
-     * TODO
+     * Update headers to include when making AJAX requests.
+     *
+     * Unless `propagate` is set to false (which is likely only useful in rare circumstances),
+     * the updated headers are propagated to all tiles and queued image loader jobs.
+     *
+     * Note that the rules for merging headers still apply, i.e. headers returned by
+     * {@link OpenSeadragon.TileSource#getTileAjaxHeaders} take precedence over
+     * the headers here in the tiled image (`TiledImage.ajaxHeaders`).
+     *
+     * @function
+     * @param {Object} ajaxHeaders Updated AJAX headers, which will be merged over any headers specified in {@link OpenSeadragon.Options}.
+     * @param {Boolean} [propagate=true] Whether to propagate updated headers to existing tiles and queued image loader jobs.
      */
     setAjaxHeaders: function(ajaxHeaders, propagate) {
         if (ajaxHeaders === null) {
@@ -1022,11 +1033,24 @@ $.extend($.TiledImage.prototype, $.EventSource.prototype, /** @lends OpenSeadrag
         }
 
         this._ownAjaxHeaders = ajaxHeaders;
-        this._updateAjaxHeaders(propagate);
+        this.updateAjaxHeaders(propagate);
     },
 
-    // private
-    _updateAjaxHeaders: function(propagate) {
+    /**
+     * Update headers to include when making AJAX requests.
+     *
+     * This function has the same effect as calling {@link OpenSeadragon.TiledImage#setAjaxHeaders},
+     * expect that the headers for this tiled image do not change. This is especially useful
+     * for propagating updated headers from {@link OpenSeadragon.TileSource#getTileAjaxHeaders}
+     * to existing tiles.
+     *
+     * Note that `TiledImage.ajaxHeaders` might still change if {@link OpenSeadragon.Viewer#setAjaxHeaders}
+     * was previously called without propagating the updated headers (not recommended).
+     *
+     * @function
+     * @param {Boolean} [propagate=true] Whether to propagate updated headers to existing tiles and queued image loader jobs.
+     */
+    updateAjaxHeaders: function(propagate) {
         if (propagate === undefined) {
             propagate = true;
         }
@@ -1038,7 +1062,7 @@ $.extend($.TiledImage.prototype, $.EventSource.prototype, /** @lends OpenSeadrag
             this.ajaxHeaders = this._ownAjaxHeaders;
         }
 
-        // propagate header updates to all tiles and queued imageloader jobs
+        // propagate header updates to all tiles and queued image loader jobs
         if (propagate) {
             var numTiles, xMod, yMod, tile;
 
@@ -1063,8 +1087,6 @@ $.extend($.TiledImage.prototype, $.EventSource.prototype, /** @lends OpenSeadrag
                 }
             }
 
-            // TODO: good enough? running jobs are not stored anywhere
-            //       maybe look through this._imageLoader.failedTiles and restart jobs? but which ones?
             for (var i = 0; i < this._imageLoader.jobQueue.length; i++) {
                 var job = this._imageLoader.jobQueue[i];
                 job.loadWithAjax = job.tile.loadWithAjax;

src/tilesource.js

@@ -663,6 +663,10 @@ $.TileSource.prototype = {
      * The headers returned here will override headers specified at the Viewer or TiledImage level.
      * Specifying a falsy value for a header will clear its existing value set at the Viewer or
      * TiledImage level (if any).
+     *
+     * Note that the headers of existing tiles don't automatically change when this function
+     * returns updated headers. To do that, you need to call {@link OpenSeadragon.TiledImage#updateAjaxHeaders}.
+     *
      * @function
      * @param {Number} level
      * @param {Number} x

src/viewer.js

@@ -979,7 +979,20 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
     },
 
     /**
-     * TODO
+     * Update headers to include when making AJAX requests.
+     *
+     * Unless `propagate` is set to false (which is likely only useful in rare circumstances),
+     * the updated headers are propagated to all tiled images, each of which will subsequently
+     * propagate the changed headers to all their tiles.
+     * If applicable, the headers of the viewer's navigator and reference strip will also be updated.
+     *
+     * Note that the rules for merging headers still apply, i.e. headers returned by
+     * {@link OpenSeadragon.TileSource#getTileAjaxHeaders} take precedence over
+     * `TiledImage.ajaxHeaders`, which take precedence over the headers here in the viewer.
+     *
+     * @function
+     * @param {Object} ajaxHeaders Updated AJAX headers.
+     * @param {Boolean} [propagate=true] Whether to propagate updated headers to tiled images, etc.
      */
     setAjaxHeaders: function(ajaxHeaders, propagate) {
         if (ajaxHeaders === null) {
@@ -1435,7 +1448,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
      * @param {Object} [options.ajaxHeaders]
      *      A set of headers to include when making tile AJAX requests.
      *      Note that these headers will be merged over any headers specified in {@link OpenSeadragon.Options}.
-     * requests.
+     *      Specifying a falsy value for a header will clear its existing value set at the Viewer level (if any).
      * @param {Function} [options.success] A function that gets called when the image is
      * successfully added. It's passed the event object which contains a single property:
      * "item", which is the resulting instance of TiledImage.