From e52e2fef3461968e62c98828ea6a6a98087cd9ee Mon Sep 17 00:00:00 2001
From: Ian Gilman <ian@iangilman.com>
Date: Wed, 5 Nov 2014 14:48:37 -0800
Subject: [PATCH] Improved docs

---
 src/imageLoader.js | 32 ++++++++++----------------------
 src/tilecache.js   | 11 +++++++++--
 src/tiledimage.js  |  2 ++
 3 files changed, 21 insertions(+), 24 deletions(-)

diff --git a/src/imageLoader.js b/src/imageLoader.js
index 0f79546c..1934051f 100644
--- a/src/imageLoader.js
+++ b/src/imageLoader.js
@@ -3,7 +3,7 @@
  *
  * Copyright (C) 2009 CodePlex Foundation
  * Copyright (C) 2010-2013 OpenSeadragon contributors
- 
+
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions are
  * met:
@@ -34,23 +34,14 @@
 
 (function( $ ){
 
-/**
- * @private
- * @class ImageJob
- * @classdesc Handles loading a single image for use in a single {@link OpenSeadragon.Tile}.
- *
- * @memberof OpenSeadragon
- * @param {String} source - URL of image to download.
- * @param {String} crossOriginPolicy - CORS policy to use for downloads
- * @param {Function} callback - Called once image has finished downloading.
- */
+// private class
 function ImageJob ( options ) {
-    
+
     $.extend( true, this, {
         timeout:        $.DEFAULT_SETTINGS.timeout,
         jobId:          null
     }, options );
-    
+
     /**
      * Image object which will contain downloaded image.
      * @member {Image} image
@@ -60,11 +51,6 @@ function ImageJob ( options ) {
 }
 
 ImageJob.prototype = {
-
-    /**
-     * Initiates downloading of associated image.
-     * @method
-     */
     start: function(){
         var _this = this;
 
@@ -104,11 +90,13 @@ ImageJob.prototype = {
 };
 
 /**
- * @class
+ * @class ImageLoader
+ * @memberof OpenSeadragon
  * @classdesc Handles downloading of a set of images using asynchronous queue pattern.
+ * You generally won't have to interact with the ImageLoader directly.
  */
 $.ImageLoader = function() {
-    
+
     $.extend( true, this, {
         jobLimit:       $.DEFAULT_SETTINGS.imageLoaderLimit,
         jobQueue:       [],
@@ -117,8 +105,8 @@ $.ImageLoader = function() {
 
 };
 
-$.ImageLoader.prototype = {
-    
+$.ImageLoader.prototype = /** @lends OpenSeadragon.ImageLoader.prototype */{
+
     /**
      * Add an unloaded image to the loader queue.
      * @method
diff --git a/src/tilecache.js b/src/tilecache.js
index 627ecc54..a643ae49 100644
--- a/src/tilecache.js
+++ b/src/tilecache.js
@@ -34,7 +34,7 @@
 
 (function( $ ){
 
-// private
+// private class
 var TileRecord = function( options ) {
     $.console.assert( options, "[TileCache.cacheTile] options is required" );
     $.console.assert( options.tile, "[TileCache.cacheTile] options.tile is required" );
@@ -43,7 +43,7 @@ var TileRecord = function( options ) {
     this.tiledImage = options.tiledImage;
 };
 
-// private
+// private class
 var ImageRecord = function(options) {
     $.console.assert( options, "[ImageRecord] options is required" );
     $.console.assert( options.image, "[ImageRecord] options.image is required" );
@@ -71,6 +71,7 @@ ImageRecord.prototype = {
     },
 
     addTile: function(tile) {
+        $.console.assert(tile, '[ImageRecord.addTile] tile is required');
         this._tiles.push(tile);
     },
 
@@ -94,6 +95,7 @@ ImageRecord.prototype = {
  * @class TileCache
  * @memberof OpenSeadragon
  * @classdesc Stores all the tiles displayed in a {@link OpenSeadragon.Viewer}.
+ * You generally won't have to interact with the TileCache directly.
  * @param {Object} options - Configuration for this TileCache.
  * @param {Number} [options.maxImageCacheCount] - See maxImageCacheCount in
  * {@link OpenSeadragon.Options} for details.
@@ -196,8 +198,10 @@ $.TileCache.prototype = /** @lends OpenSeadragon.TileCache.prototype */{
 
     /**
      * Clears all tiles associated with the specified tiledImage.
+     * @param {OpenSeadragon.TiledImage} tiledImage
      */
     clearTilesFor: function( tiledImage ) {
+        $.console.assert(tiledImage, '[TileCache.clearTilesFor] tiledImage is required');
         var tileRecord;
         for ( var i = 0; i < this._tilesLoaded.length; ++i ) {
             tileRecord = this._tilesLoaded[ i ];
@@ -209,12 +213,15 @@ $.TileCache.prototype = /** @lends OpenSeadragon.TileCache.prototype */{
         }
     },
 
+    // private
     getImageRecord: function(url) {
+        $.console.assert(url, '[TileCache.getImageRecord] url is required');
         return this._imagesLoaded[url];
     },
 
     // private
     _unloadTile: function(tile) {
+        $.console.assert(tile, '[TileCache._unloadTile] tile is required');
         tile.unload();
         tile.cacheImageRecord = null;
 
diff --git a/src/tiledimage.js b/src/tiledimage.js
index 6d169d40..4467d971 100644
--- a/src/tiledimage.js
+++ b/src/tiledimage.js
@@ -35,6 +35,8 @@
 (function( $ ){
 
 /**
+ * You shouldn't have to create a TiledImage directly; use {@link OpenSeadragon.Viewer#open}
+ * or {@link OpenSeadragon.Viewer#addTiledImage} instead.
  * @class TiledImage
  * @memberof OpenSeadragon
  * @classdesc Handles rendering of tiles for an {@link OpenSeadragon.Viewer}.