Clarify documentation on cache-key creation.

src/tile.js

@@ -52,7 +52,7 @@
  * @param {OpenSeadragon.Rect} sourceBounds The portion of the tile to use as the source of the
  *      drawing operation, in pixels. Note that this only works when drawing with canvas; when drawing
  *      with HTML the entire tile is always used.
- * @param {String} postData HTTP POST data  (usually but not necessarily in k=v&k2=v2... form,
+ * @param {String} postData HTTP POST data (usually but not necessarily in k=v&k2=v2... form,
  *      see TileSrouce::getPostData) or null
  * @param {String} cacheKey key to act as a tile cache, must be unique for tiles with unique image data
  */
@@ -101,8 +101,8 @@ $.Tile = function(level, x, y, bounds, exists, url, context2D, loadWithAjax, aja
      */
     this.url     = url;
     /**
-     * Post parameters for this tile. Either it is an URL-encoded string
+     * Post parameters for this tile. For example, it can be an URL-encoded string
-     * in k1=v1&k2=v2... format or null
+     * in k1=v1&k2=v2... format, or a JSON, or a FormData instance... or null if no POST request used
      * @member {String} postData HTTP POST data (usually but not necessarily in k=v&k2=v2... form,
      *      see TileSrouce::getPostData) or null
      * @memberof OpenSeadragon.Tile#

src/tilesource.js

@@ -644,9 +644,9 @@ $.TileSource.prototype = {
      * to post data, you must re-define 'getTileHashKey(...)' to
      * stay unique for different tile images.
      *
-     * @param level
+     * @param {Number} level
-     * @param x
+     * @param {Number} x
-     * @param y
+     * @param {Number} y
      * @return {* || null} post data to send with tile configuration request
      */
     getTilePostData: function( level, x, y ) {
@@ -671,17 +671,19 @@ $.TileSource.prototype = {
     },
 
     /**
-     * A tile can have either context2D defined (TileSource.prototype.getContext2D)
+     * The tile cache object is uniquely determined by this key and used to lookup
-     * or its context2D is set manually. In those cases cache is not used and this function
+     * the image data in cache: keys should be different if images are different.
-     * is irrelevant. Otherwise, the tile cache object is uniquely determined by this key:
+     *
-     * keys should be different if images are different!
+     * In case a tile has context2D property defined (TileSource.prototype.getContext2D)
+     * or its context2D is set manually; the cache is not used and this function
+     * is irrelevant.
      * Note: default behaviour does not take into account post data.
-     * @param level tile level it was fetched with
+     * @param {Number} level tile level it was fetched with
-     * @param x x-coordinate in the pyramid level
+     * @param {Number} x x-coordinate in the pyramid level
-     * @param y y-coordinate in the pyramid level
+     * @param {Number} y y-coordinate in the pyramid level
-     * @param url the tile was fetched with
+     * @param {String} url the tile was fetched with
-     * @param ajaxHeaders the tile was fetched with
+     * @param {Object} ajaxHeaders the tile was fetched with
-     * @param postData data the tile was fetched with
+     * @param {*} postData data the tile was fetched with (type depends on getTilePostData(..) return type)
      */
     getTileHashKey: function(level, x, y, url, ajaxHeaders, postData) {
         if (ajaxHeaders) {