Updated documentation

changelog.txt

@@ -5,6 +5,7 @@ OPENSEADRAGON CHANGELOG
 
 * True multi-image mode (#450)
     * BREAKING CHANGE: Navigator no longer sends an open event when its viewer opens
+    * BREAKING CHANGE: Viewer.drawers and Viewer.drawersContainer no longer exist
     * DEPRECATION: use Viewer.addTiledImage instead of Viewer.addLayer
         * addTiledImage supports positioning config properties
     * DEPRECATION: use World.getItemAt instead of Viewer.getLayerAtLevel
@@ -17,7 +18,6 @@ OPENSEADRAGON CHANGELOG
     * DEPRECATION: use World.resetItems instead of Drawer.reset
     * DEPRECATION: use Drawer.clear and World.update instead of Drawer.update
     * DEPRECATION: the layersAspectRatioEpsilon option is no longer necessary
-    * DEPRECATION: Viewer.drawers and Viewer.drawersContainer no longer exist
     * DEPRECATION: Viewer's add-layer event is now World's add-item event
     * DEPRECATION: Viewer's layer-level-changed event is now World's item-index-changed event
     * DEPRECATION: Viewer's remove-layer event is now World's remove-item event
@@ -31,6 +31,7 @@ OPENSEADRAGON CHANGELOG
     * Rect and Point now have clone functions
     * New Viewport method for managing homeBounds as well as constraints: setHomeBounds
     * Viewport.open supports positioning config properties
+* Margins option to push the home region in from the edges of the Viewer (#505)
 
 1.2.0: (in progress)
 

src/drawer.js

@@ -36,15 +36,17 @@
 
 /**
  * @class Drawer
- * @classdesc Handles rendering of tiles for an {@link OpenSeadragon.Viewer}.
- *
  * @memberof OpenSeadragon
- * @param {OpenSeadragon.TileSource} source - Reference to Viewer tile source.
+ * @classdesc Handles rendering of tiles for an {@link OpenSeadragon.Viewer}.
- * @param {OpenSeadragon.Viewport} viewport - Reference to Viewer viewport.
+ * @param {Object} options - Options for this Drawer.
- * @param {Element} element - Parent element.
+ * @param {OpenSeadragon.Viewer} options.viewer - The Viewer that owns this Drawer.
+ * @param {OpenSeadragon.Viewport} options.viewport - Reference to Viewer viewport.
+ * @param {Element} options.element - Parent element.
+ * @param {Number} [options.opacity=1] - See opacity in {@link OpenSeadragon.Options} for details.
+ * @param {Number} [options.debugGridColor] - See debugGridColor in {@link OpenSeadragon.Options} for details.
  */
 $.Drawer = function( options ) {
-    var self = this;
+    var _this = this;
 
     $.console.assert( options.viewer, "[Drawer] options.viewer is required" );
 
@@ -117,7 +119,7 @@ $.Drawer = function( options ) {
 
     // We need a callback to give image manipulation a chance to happen
     this._drawingHandler = function(args) {
-        if (self.viewer) {
+        if (_this.viewer) {
           /**
            * This event is fired just before the tile is drawn giving the application a chance to alter the image.
            *
@@ -130,80 +132,34 @@ $.Drawer = function( options ) {
            * @property {OpenSeadragon.Tile} tile
            * @property {?Object} userData - 'context', 'tile' and 'rendered'.
            */
-            self.viewer.raiseEvent('tile-drawing', args);
+            _this.viewer.raiseEvent('tile-drawing', args);
         }
     };
 };
 
 $.Drawer.prototype = /** @lends OpenSeadragon.Drawer.prototype */{
-
+    // deprecated
-    /**
-     * Adds an html element as an overlay to the current viewport.  Useful for
-     * highlighting words or areas of interest on an image or other zoomable
-     * interface.
-     * @method
-     * @param {Element|String|Object} element - A reference to an element or an id for
-     *      the element which will overlayed. Or an Object specifying the configuration for the overlay
-     * @param {OpenSeadragon.Point|OpenSeadragon.Rect} location - The point or
-     *      rectangle which will be overlayed.
-     * @param {OpenSeadragon.OverlayPlacement} placement - The position of the
-     *      viewport which the location coordinates will be treated as relative
-     *      to.
-     * @param {function} onDraw - If supplied the callback is called when the overlay
-     *      needs to be drawn. It it the responsibility of the callback to do any drawing/positioning.
-     *      It is passed position, size and element.
-     * @fires OpenSeadragon.Viewer.event:add-overlay
-     * @deprecated - use {@link OpenSeadragon.Viewer#addOverlay} instead.
-     */
     addOverlay: function( element, location, placement, onDraw ) {
         $.console.error("drawer.addOverlay is deprecated. Use viewer.addOverlay instead.");
         this.viewer.addOverlay( element, location, placement, onDraw );
         return this;
     },
 
-    /**
+    // deprecated
-     * Updates the overlay represented by the reference to the element or
-     * element id moving it to the new location, relative to the new placement.
-     * @method
-     * @param {OpenSeadragon.Point|OpenSeadragon.Rect} location - The point or
-     *      rectangle which will be overlayed.
-     * @param {OpenSeadragon.OverlayPlacement} placement - The position of the
-     *      viewport which the location coordinates will be treated as relative
-     *      to.
-     * @return {OpenSeadragon.Drawer} Chainable.
-     * @fires OpenSeadragon.Viewer.event:update-overlay
-     * @deprecated - use {@link OpenSeadragon.Viewer#updateOverlay} instead.
-     */
     updateOverlay: function( element, location, placement ) {
         $.console.error("drawer.updateOverlay is deprecated. Use viewer.updateOverlay instead.");
         this.viewer.updateOverlay( element, location, placement );
         return this;
     },
 
-    /**
+    // deprecated
-     * Removes and overlay identified by the reference element or element id
-     *      and schedules and update.
-     * @method
-     * @param {Element|String} element - A reference to the element or an
-     *      element id which represent the ovelay content to be removed.
-     * @return {OpenSeadragon.Drawer} Chainable.
-     * @fires OpenSeadragon.Viewer.event:remove-overlay
-     * @deprecated - use {@link OpenSeadragon.Viewer#removeOverlay} instead.
-     */
     removeOverlay: function( element ) {
         $.console.error("drawer.removeOverlay is deprecated. Use viewer.removeOverlay instead.");
         this.viewer.removeOverlay( element );
         return this;
     },
 
-    /**
+    // deprecated
-     * Removes all currently configured Overlays from this Drawer and schedules
-     *      and update.
-     * @method
-     * @return {OpenSeadragon.Drawer} Chainable.
-     * @fires OpenSeadragon.Viewer.event:clear-overlay
-     * @deprecated - use {@link OpenSeadragon.Viewer#clearOverlays} instead.
-     */
     clearOverlays: function() {
         $.console.error("drawer.clearOverlays is deprecated. Use viewer.clearOverlays instead.");
         this.viewer.clearOverlays();
@@ -212,7 +168,6 @@ $.Drawer.prototype = /** @lends OpenSeadragon.Drawer.prototype */{
 
     /**
      * Set the opacity of the drawer.
-     * @method
      * @param {Number} opacity
      * @return {OpenSeadragon.Drawer} Chainable.
      */
@@ -224,60 +179,37 @@ $.Drawer.prototype = /** @lends OpenSeadragon.Drawer.prototype */{
 
     /**
      * Get the opacity of the drawer.
-     * @method
      * @returns {Number}
      */
     getOpacity: function() {
         return this.opacity;
     },
 
-    /**
+    // deprecated
-     * Returns whether the Drawer is scheduled for an update at the
-     *      soonest possible opportunity.
-     * @method
-     * @returns {Boolean} - Whether the Drawer is scheduled for an update at the
-     *      soonest possible opportunity.
-     */
     needsUpdate: function() {
         $.console.error( "[Drawer.needsUpdate] this function is deprecated." );
         return false;
     },
 
-    /**
+    // deprecated
-     * Returns the total number of tiles that have been loaded by this Drawer.
-     * @method
-     * @returns {Number} - The total number of tiles that have been loaded by
-     *      this Drawer.
-     */
     numTilesLoaded: function() {
         $.console.error( "[Drawer.numTilesLoaded] this function is deprecated." );
         return 0;
     },
 
-    /**
+    // deprecated
-     * Clears all tiles and triggers an update on the next call to
-     * Drawer.prototype.update().
-     * @method
-     * @return {OpenSeadragon.Drawer} Chainable.
-     */
     reset: function() {
         $.console.error( "[Drawer.reset] this function is deprecated." );
         return this;
     },
 
-    /**
+    // deprecated
-     * Forces the Drawer to update.
-     * @method
-     * @return {OpenSeadragon.Drawer} Chainable.
-     */
     update: function() {
         $.console.error( "[Drawer.update] this function is deprecated." );
         return this;
     },
 
     /**
-     * Returns whether rotation is supported or not.
-     * @method
      * @return {Boolean} True if rotation is supported.
      */
     canRotate: function() {
@@ -286,8 +218,6 @@ $.Drawer.prototype = /** @lends OpenSeadragon.Drawer.prototype */{
 
     /**
      * Destroy the drawer (unload current loaded tiles)
-     * @method
-     * @return null
      */
     destroy: function() {
         //force unloading of current canvas (1x1 will be gc later, trick not necessarily needed)
@@ -295,6 +225,9 @@ $.Drawer.prototype = /** @lends OpenSeadragon.Drawer.prototype */{
         this.canvas.height = 1;
     },
 
+    /**
+     * Clears the Drawer so it's ready to draw another frame.
+     */
     clear: function() {
         this.canvas.innerHTML = "";
         if ( this.useCanvas ) {
@@ -308,6 +241,10 @@ $.Drawer.prototype = /** @lends OpenSeadragon.Drawer.prototype */{
         }
     },
 
+    /**
+     * Draws the given tile.
+     * @param {OpenSeadragon.Tile} tile - The tile to draw.
+     */
     drawTile: function( tile ) {
         if ( this.useCanvas ) {
             // TODO do this in a more performant way
@@ -324,9 +261,7 @@ $.Drawer.prototype = /** @lends OpenSeadragon.Drawer.prototype */{
         }
     },
 
-    /**
+    // private
-     * @private
-     */
     drawDebugInfo: function( tile, count, i ){
         if ( this.useCanvas ) {
             this.context.save();
@@ -399,9 +334,7 @@ $.Drawer.prototype = /** @lends OpenSeadragon.Drawer.prototype */{
         }
     },
 
-    /**
+    // private
-     * @private
-     */
     debugRect: function(rect) {
         if ( this.useCanvas ) {
             this.context.save();
@@ -420,9 +353,7 @@ $.Drawer.prototype = /** @lends OpenSeadragon.Drawer.prototype */{
         }
     },
 
-    /**
+    // private
-     * @private
-     */
     _offsetForRotation: function( tile, degrees ){
         var cx = this.canvas.width / 2,
             cy = this.canvas.height / 2,
@@ -437,9 +368,7 @@ $.Drawer.prototype = /** @lends OpenSeadragon.Drawer.prototype */{
         tile.position.y = py;
     },
 
-    /**
+    // private
-     * @private
-     */
     _restoreRotationChanges: function( tile ){
         var cx = this.canvas.width / 2,
             cy = this.canvas.height / 2,

src/navigator.js

@@ -344,10 +344,7 @@ $.extend( $.Navigator.prototype, $.EventSource.prototype, $.Viewer.prototype, /*
 
     },
 
-    /**
+    // overrides Viewer.addTiledImage
-     * Overrides Viewer.addTiledImage
-     * @private
-     */
     addTiledImage: function(options) {
         var original = options.originalTiledImage;
         delete options.original;

src/openseadragon.js

@@ -2251,7 +2251,7 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
         info:   nullfunction,
         warn:   nullfunction,
         error:  nullfunction,
-        assert:  nullfunction
+        assert: nullfunction
     };
 
 

src/tilecache.js

@@ -34,17 +34,22 @@
 
 (function( $ ){
 
-var TileRecord = function( params ) {
+// private
-    $.console.assert( params, "[TileCache.cacheTile] params is required" );
+var TileRecord = function( options ) {
-    $.console.assert( params.tile, "[TileCache.cacheTile] params.tile is required" );
+    $.console.assert( options, "[TileCache.cacheTile] options is required" );
-    $.console.assert( params.tiledImage, "[TileCache.cacheTile] params.tiledImage is required" );
+    $.console.assert( options.tile, "[TileCache.cacheTile] options.tile is required" );
-    this.tile = params.tile;
+    $.console.assert( options.tiledImage, "[TileCache.cacheTile] options.tiledImage is required" );
-    this.tiledImage = params.tiledImage;
+    this.tile = options.tile;
+    this.tiledImage = options.tiledImage;
 };
 
 /**
  * @class TileCache
- * @classdesc
+ * @memberof OpenSeadragon
+ * @classdesc Stores all the tiles displayed in a {@link OpenSeadragon.Viewer}.
+ * @param {Object} options - Configuration for this TileCache.
+ * @param {Number} [options.maxImageCacheCount] - See maxImageCacheCount in
+ * {@link OpenSeadragon.Options} for details.
  */
 $.TileCache = function( options ) {
     options = options || {};
@@ -55,21 +60,29 @@ $.TileCache = function( options ) {
 
 $.TileCache.prototype = /** @lends OpenSeadragon.TileCache.prototype */{
     /**
-     * Returns the total number of tiles that have been loaded by this TileCache.
+     * @returns {Number} The total number of tiles that have been loaded by
-     * @method
+     * this TileCache.
-     * @returns {Number} - The total number of tiles that have been loaded by
-     *      this TileCache.
      */
     numTilesLoaded: function() {
         return this._tilesLoaded.length;
     },
 
-    cacheTile: function( params ) {
+    /**
-        $.console.assert( params, "[TileCache.cacheTile] params is required" );
+     * Caches the specified tile, removing an old tile if necessary to stay under the
-        $.console.assert( params.tile, "[TileCache.cacheTile] params.tile is required" );
+     * maxImageCacheCount specified on construction.
-        $.console.assert( params.tiledImage, "[TileCache.cacheTile] params.tiledImage is required" );
+     * @param {Object} options - Tile info.
+     * @param {OpenSeadragon.Tile} options.tile - The tile to cache.
+     * @param {OpenSeadragon.TiledImage} options.tiledImage - The TiledImage that owns that tile.
+     * @param {Number} [options.cutoff=0] - If adding this tile goes over the cache max count, this
+     * function will release an old tile. The cutoff option specifies a tile level at or below which
+     * tiles will not be released.
+     */
+    cacheTile: function( options ) {
+        $.console.assert( options, "[TileCache.cacheTile] options is required" );
+        $.console.assert( options.tile, "[TileCache.cacheTile] options.tile is required" );
+        $.console.assert( options.tiledImage, "[TileCache.cacheTile] options.tiledImage is required" );
 
-        var cutoff = params.cutoff || 0;
+        var cutoff = options.cutoff || 0;
         var insertionIndex = this._tilesLoaded.length;
 
         if ( this._tilesLoaded.length >= this._maxImageCacheCount ) {
@@ -108,14 +121,13 @@ $.TileCache.prototype = /** @lends OpenSeadragon.TileCache.prototype */{
         }
 
         this._tilesLoaded[ insertionIndex ] = new TileRecord({
-            tile: params.tile,
+            tile: options.tile,
-            tiledImage: params.tiledImage
+            tiledImage: options.tiledImage
         });
     },
 
     /**
      * Clears all tiles associated with the specified tiledImage.
-     * @method
      */
     clearTilesFor: function( tiledImage ) {
         var tileRecord;

src/tiledimage.js

@@ -36,16 +36,35 @@
 
 /**
  * @class TiledImage
+ * @memberof OpenSeadragon
  * @classdesc Handles rendering of tiles for an {@link OpenSeadragon.Viewer}.
  * A new instance is created for each TileSource opened.
- *
+ * @param {Object} options - Configuration for this TiledImage.
- * @memberof OpenSeadragon
+ * @param {OpenSeadragon.TileSource} options.source - The TileSource that defines this TiledImage.
+ * @param {OpenSeadragon.Viewer} options.viewer - The Viewer that owns this TiledImage.
+ * @param {OpenSeadragon.TileCache} options.tileCache - The TileCache for this TiledImage to use.
+ * @param {OpenSeadragon.Drawer} options.drawer - The Drawer for this TiledImage to draw onto.
+ * @param {OpenSeadragon.ImageLoader} options.imageLoader - The ImageLoader for this TiledImage to use.
+ * @param {Number} [options.x=0] - Left position, in world coordinates.
+ * @param {Number} [options.y=0] - Top position, in world coordinates.
+ * @param {Number} [options.width=1] - Width, in world coordinates.
+ * @param {Number} [options.height] - Height, in world coordinates.
+ * @param {Number} [options.minZoomImageRatio] - See {@link OpenSeadragon.Options}.
+ * @param {Boolean} [options.wrapHorizontal] - See {@link OpenSeadragon.Options}.
+ * @param {Boolean} [options.wrapVertical] - See {@link OpenSeadragon.Options}.
+ * @param {Boolean} [options.immediateRender] - See {@link OpenSeadragon.Options}.
+ * @param {Number} [options.blendTime] - See {@link OpenSeadragon.Options}.
+ * @param {Boolean} [options.alwaysBlend] - See {@link OpenSeadragon.Options}.
+ * @param {Number} [options.minPixelRatio] - See {@link OpenSeadragon.Options}.
+ * @param {Boolean} [options.debugMode] - See {@link OpenSeadragon.Options}.
+ * @param {String|Boolean} [options.crossOriginPolicy] - See {@link OpenSeadragon.Options}.
  */
 $.TiledImage = function( options ) {
     $.console.assert( options.tileCache, "[TiledImage] options.tileCache is required" );
     $.console.assert( options.drawer, "[TiledImage] options.drawer is required" );
     $.console.assert( options.viewer, "[TiledImage] options.viewer is required" );
     $.console.assert( options.imageLoader, "[TiledImage] options.imageLoader is required" );
+    $.console.assert( options.source, "[TiledImage] options.source is required" );
 
     this._tileCache = options.tileCache;
     delete options.tileCache;
@@ -109,11 +128,8 @@ $.TiledImage = function( options ) {
 
 $.TiledImage.prototype = /** @lends OpenSeadragon.TiledImage.prototype */{
     /**
-     * Returns whether the TiledImage is scheduled for an update at the
+     * @returns {Boolean} Whether the TiledImage is scheduled for an update at the
-     *      soonest possible opportunity.
+     * soonest possible opportunity.
-     * @method
-     * @returns {Boolean} - Whether the TiledImage is scheduled for an update at the
-     *      soonest possible opportunity.
      */
     needsUpdate: function() {
         return this.updateAgain;
@@ -121,42 +137,40 @@ $.TiledImage.prototype = /** @lends OpenSeadragon.TiledImage.prototype */{
 
     /**
      * Clears all tiles and triggers an update on the next call to
-     * TiledImage.prototype.update().
+     * {@link OpenSeadragon.TiledImage#update}.
-     * @method
-     * @return {OpenSeadragon.TiledImage} Chainable.
      */
     reset: function() {
         this._tileCache.clearTilesFor(this);
         this.lastResetTime = $.now();
         this.updateAgain = true;
-        return this;
     },
 
     /**
      * Forces the TiledImage to update.
-     * @method
-     * @return {OpenSeadragon.TiledImage} Chainable.
      */
     update: function() {
         this.midUpdate = true;
         updateViewport( this );
         this.midUpdate = false;
-        return this;
     },
 
     /**
-     * Destroy the TiledImage (unload current loaded tiles)
+     * Destroy the TiledImage (unload current loaded tiles).
-     * @method
-     * @return null
      */
     destroy: function() {
         this.reset();
     },
 
+    /**
+     * @returns {OpenSeadragon.Rect} This TiledImage's bounds in world coordinates.
+     */
     getWorldBounds: function() {
         return new $.Rect( this._worldX, this._worldY, this._worldWidth, this._worldHeight );
     },
 
+    /**
+     * @returns {OpenSeadragon.Point} This TiledImage's content size, in original pixels.
+     */
     getContentSize: function() {
         return new $.Point(this.source.dimensions.x, this.source.dimensions.y);
     }

src/viewer.js

@@ -539,17 +539,13 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
         return !!this.world.getItemCount();
     },
 
-    /**
+    // deprecated
-     * @private
-     */
     openDzi: function ( dzi ) {
         $.console.error( "[Viewer.openDzi] this function is deprecated; use Viewer.open() instead." );
         return this.open( dzi );
     },
 
-    /**
+    // deprecated
-     * @private
-     */
     openTileSource: function ( tileSource ) {
         $.console.error( "[Viewer.openTileSource] this function is deprecated; use Viewer.open() instead." );
         return this.open( tileSource );
@@ -1329,24 +1325,21 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
         } );
     },
 
-    /**
+    // deprecated
-     * @function
-     * @private
-     */
     addLayer: function( options ) {
-        var self = this;
+        var _this = this;
 
         $.console.error( "[Viewer.addLayer] this function is deprecated; use Viewer.addTiledImage() instead." );
 
         var optionsClone = $.extend({}, options, {
             success: function(event) {
-                self.raiseEvent("add-layer", {
+                _this.raiseEvent("add-layer", {
                     options: options,
                     drawer: event.item
                 });
             },
             error: function(event) {
-                self.raiseEvent("add-layer-failed", event);
+                _this.raiseEvent("add-layer-failed", event);
             }
         });
 
@@ -1354,46 +1347,31 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
         return this;
     },
 
-    /**
+    // deprecated
-     * @function
-     * @private
-     */
     getLayerAtLevel: function( level ) {
         $.console.error( "[Viewer.getLayerAtLevel] this function is deprecated; use World.getItemAt() instead." );
         return this.world.getItemAt(level);
     },
 
-    /**
+    // deprecated
-     * @function
-     * @private
-     */
     getLevelOfLayer: function( drawer ) {
         $.console.error( "[Viewer.getLevelOfLayer] this function is deprecated; use World.getIndexOfItem() instead." );
         return this.world.getIndexOfItem(drawer);
     },
 
-    /**
+    // deprecated
-     * @function
-     * @private
-     */
     getLayersCount: function() {
         $.console.error( "[Viewer.getLayersCount] this function is deprecated; use World.getItemCount() instead." );
         return this.world.getItemCount();
     },
 
-    /**
+    // deprecated
-     * @function
-     * @private
-     */
     setLayerLevel: function( drawer, level ) {
         $.console.error( "[Viewer.setLayerLevel] this function is deprecated; use World.setItemIndex() instead." );
         return this.world.setItemIndex(drawer, level);
     },
 
-    /**
+    // deprecated
-     * @function
-     * @private
-     */
     removeLayer: function( drawer ) {
         $.console.error( "[Viewer.removeLayer] this function is deprecated; use World.removeItem() instead." );
         return this.world.removeItem(drawer);

src/viewport.js

@@ -37,10 +37,23 @@
 
 /**
  * @class Viewport
- * @classdesc Handles coordinate-related functionality (zoom, pan, rotation, etc.) for an {@link OpenSeadragon.Viewer}.
- * A new instance is created for each TileSource opened (see {@link OpenSeadragon.Viewer#viewport}).
- *
  * @memberof OpenSeadragon
+ * @classdesc Handles coordinate-related functionality (zoom, pan, rotation, etc.)
+ * for an {@link OpenSeadragon.Viewer}.
+ * @param {Object} options - Options for this Viewport.
+ * @param {Object} [margins] - See viewportMargins in {@link OpenSeadragon.Options}.
+ * @param {Number} [springStiffness] - See springStiffness in {@link OpenSeadragon.Options}.
+ * @param {Number} [animationTime] - See animationTime in {@link OpenSeadragon.Options}.
+ * @param {Number} [minZoomImageRatio] - See minZoomImageRatio in {@link OpenSeadragon.Options}.
+ * @param {Number} [maxZoomPixelRatio] - See maxZoomPixelRatio in {@link OpenSeadragon.Options}.
+ * @param {Number} [visibilityRatio] - See visibilityRatio in {@link OpenSeadragon.Options}.
+ * @param {Boolean} [wrapHorizontal] - See wrapHorizontal in {@link OpenSeadragon.Options}.
+ * @param {Boolean} [wrapVertical] - See wrapVertical in {@link OpenSeadragon.Options}.
+ * @param {Number} [defaultZoomLevel] - See defaultZoomLevel in {@link OpenSeadragon.Options}.
+ * @param {Number} [minZoomLevel] - See minZoomLevel in {@link OpenSeadragon.Options}.
+ * @param {Number} [maxZoomLevel] - See maxZoomLevel in {@link OpenSeadragon.Options}.
+ * @param {Number} [degrees] - See degrees in {@link OpenSeadragon.Options}.
+ * @param {Boolean} [homeFillsViewer] - See homeFillsViewer in {@link OpenSeadragon.Options}.
  */
 $.Viewport = function( options ) {
 
@@ -933,9 +946,7 @@ $.Viewport.prototype = /** @lends OpenSeadragon.Viewport.prototype */{
         return this._pixelFromPoint(point, this.getBounds( current ));
     },
 
-    /**
+    // private
-     * @private
-     */
     _pixelFromPoint: function( point, bounds ) {
         return point.minus(
             bounds.getTopLeft()

src/world.js

@@ -35,14 +35,12 @@
 (function( $ ){
 
 /**
- * Keeps track of all of the tiled images in the scene.
- *
  * @class World
- * @classdesc
- *
  * @memberof OpenSeadragon
  * @extends OpenSeadragon.EventSource
- * @param {OpenSeadragon.Options} options - World options.
+ * @classdesc Keeps track of all of the tiled images in the scene.
+ * @param {Object} options - World options.
+ * @param {OpenSeadragon.Viewer} options.viewer - The Viewer that owns this World.
  **/
 $.World = function( options ) {
     $.console.assert( options.viewer, "[World] options.viewer is required" );
@@ -59,7 +57,7 @@ $.extend( $.World.prototype, $.EventSource.prototype, /** @lends OpenSeadragon.W
     /**
      * Add the specified item.
      * @param {OpenSeadragon.TiledImage} item - The item to add.
-     * @param {Number} options.index - index for the item (optional).
+     * @param {Number} [options.index] - Index for the item. If not specified, goes at the top.
      * @fires OpenSeadragon.World.event:add-item
      */
     addItem: function( item, options ) {
@@ -83,7 +81,7 @@ $.extend( $.World.prototype, $.EventSource.prototype, /** @lends OpenSeadragon.W
          * @memberOf OpenSeadragon.World
          * @type {object}
          * @property {OpenSeadragon.Viewer} eventSource - A reference to the World which raised the event.
-         * @property {OpenSeadragon.Drawer} item - The item that has been added
+         * @property {OpenSeadragon.TiledImage} item - The item that has been added.
          * @property {?Object} userData - Arbitrary subscriber-defined object.
          */
         this.raiseEvent( 'add-item', {
@@ -112,7 +110,6 @@ $.extend( $.World.prototype, $.EventSource.prototype, /** @lends OpenSeadragon.W
     },
 
     /**
-     * Get the number of items used.
      * @returns {Number} The number of items used.
      */
     getItemCount: function() {
@@ -164,7 +161,6 @@ $.extend( $.World.prototype, $.EventSource.prototype, /** @lends OpenSeadragon.W
 
     /**
      * Remove an item.
-     * @function
      * @param {OpenSeadragon.TiledImage} item - The item to remove.
      * @fires OpenSeadragon.World.event:remove-item
      */
@@ -184,7 +180,6 @@ $.extend( $.World.prototype, $.EventSource.prototype, /** @lends OpenSeadragon.W
 
     /**
      * Remove all items.
-     * @function
      * @fires OpenSeadragon.World.event:remove-item
      */
     removeAll: function() {
@@ -200,7 +195,6 @@ $.extend( $.World.prototype, $.EventSource.prototype, /** @lends OpenSeadragon.W
 
     /**
      * Clears all tiles and triggers updates for all items.
-     * @function
      */
     resetItems: function() {
         for ( var i = 0; i < this._items.length; i++ ) {
@@ -210,7 +204,6 @@ $.extend( $.World.prototype, $.EventSource.prototype, /** @lends OpenSeadragon.W
 
     /**
      * Updates (i.e. draws) all items.
-     * @function
      */
     update: function() {
         for ( var i = 0; i < this._items.length; i++ ) {
@@ -221,7 +214,6 @@ $.extend( $.World.prototype, $.EventSource.prototype, /** @lends OpenSeadragon.W
     },
 
     /**
-     * @function
      * @returns {Boolean} true if any items need updating.
      */
     needsUpdate: function() {
@@ -234,8 +226,7 @@ $.extend( $.World.prototype, $.EventSource.prototype, /** @lends OpenSeadragon.W
     },
 
     /**
-     * @function
+     * @returns {OpenSeadragon.Rect} The smallest rectangle that encloses all items, in world coordinates.
-     * @returns {OpenSeadragon.Rect} the smallest rectangle that encloses all items, in world coordinates.
      */
     getHomeBounds: function() {
         return this._homeBounds.clone();
@@ -245,17 +236,13 @@ $.extend( $.World.prototype, $.EventSource.prototype, /** @lends OpenSeadragon.W
      * To facilitate zoom constraints, we keep track of the pixel density of the
      * densest item in the World (i.e. the item whose content size to world size
      * ratio is the highest) and save it as this "content factor".
-     * @function
      * @returns {Number} the number of content units per world unit.
      */
     getContentFactor: function() {
         return this._contentFactor;
     },
 
-    /**
+    // private
-     * @function
-     * @private
-     */
     _figureSizes: function() {
         if ( !this._items.length ) {
             this._homeBounds = new $.Rect(0, 0, 1, 1);
@@ -284,10 +271,7 @@ $.extend( $.World.prototype, $.EventSource.prototype, /** @lends OpenSeadragon.W
             this._homeBounds.height * this._contentFactor);
     },
 
-    /**
+    // private
-     * @function
-     * @private
-     */
     _raiseRemoveItem: function(item) {
         /**
          * Raised when a item is removed.