Merged upstream changes, fixed conflicts

Gruntfile.js

@@ -55,6 +55,12 @@ module.exports = function(grunt) {
     // Project configuration.
     grunt.initConfig({
         pkg: packageJson,
+        osdVersion: {
+            versionStr: packageJson.version,
+            major:      parseInt(packageJson.version.split('.')[0], 10),
+            minor:      parseInt(packageJson.version.split('.')[1], 10),
+            revision:   parseInt(packageJson.version.split('.')[2], 10)
+        },
         clean: {
             build: ["build"],
             package: [packageDir],

changelog.txt

@@ -29,6 +29,7 @@ OPENSEADRAGON CHANGELOG
     * There is now a 'full-screen' event with a `fullScreen` property (true if it has gone to full screen).
     * There are now 'pre-full-page' and 'pre-full-screen' events that include a `preventDefaultAction` property you can set in your handler to cancel. They also have `fullPage` and `fullScreen` properties respectively, to indicate if they are going into or out of the mode.
 * BREAKING CHANGE: Removed the 'onPageChange' callback from the viewer options. Viewer.goToPage() now raises the 'page' event only (#285)
+* Major documentation improvements (#281)
 * MouseTracker now passes the original event objects to its handler methods (#23)
 * MouseTracker now supports an optional 'moveHandler' method for tracking mousemove events (#215)
 * Added stopHandler to MouseTracker. (#262)
@@ -56,7 +57,8 @@ OPENSEADRAGON CHANGELOG
     * Viewer.innerTracker.scrollHandler: preventDefaultAction == true prevents viewer zooming on mousewheel/pinch
 * Fixed: IE8 error with custom buttons - "Object doesn't support this action" (#279)
 * Support IIIF servers that don't report tile dimensions (#286)
-* Added an autoResize option. Default is true. When set to false, the viewer takes no action when its container element is resized.
+* Added an autoResize option. Default is true. When set to false, the viewer takes no action when its container element is resized. (#291)
+* Added a static 'version' property to OpenSeadragon. Useful for plugins that require specific OpenSeadragon versions. (#292)
 
 0.9.131:
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "OpenSeadragon",
-  "version": "0.9.131",
+  "version": "1.0.0",
   "description": "Provides a smooth, zoomable user interface for HTML/Javascript.",
   "devDependencies": {
     "grunt": "~0.4.1",

src/button.js

@@ -35,8 +35,15 @@
 (function( $ ){
 
 /**
- * An enumeration of button states including, REST, GROUP, HOVER, and DOWN
+ * An enumeration of button states
+ * @member ButtonState
+ * @memberof OpenSeadragon
  * @static
+ * @type {Object}
+ * @property {Number} REST
+ * @property {Number} GROUP
+ * @property {Number} HOVER
+ * @property {Number} DOWN
  */
 $.ButtonState = {
     REST:   0,
@@ -46,38 +53,30 @@ $.ButtonState = {
 };
 
 /**
- * Manages events, hover states for individual buttons, tool-tips, as well
+ * @class Button
- * as fading the bottons out when the user has not interacted with them
+ * @classdesc Manages events, hover states for individual buttons, tool-tips, as well
+ * as fading the buttons out when the user has not interacted with them
  * for a specified period.
- * @class
+ *
+ * @memberof OpenSeadragon
  * @extends OpenSeadragon.EventSource
  * @param {Object} options
- * @param {String} options.tooltip Provides context help for the button we the
+ * @param {Element} [options.element=null] Element to use as the button. If not specified, an HTML <button> element is created.
+ * @param {String} [options.tooltip=null] Provides context help for the button when the
  *  user hovers over it.
- * @param {String} options.srcRest URL of image to use in 'rest' state
+ * @param {String} [options.srcRest=null] URL of image to use in 'rest' state.
- * @param {String} options.srcGroup URL of image to use in 'up' state
+ * @param {String} [options.srcGroup=null] URL of image to use in 'up' state.
- * @param {String} options.srcHover URL of image to use in 'hover' state
+ * @param {String} [options.srcHover=null] URL of image to use in 'hover' state.
- * @param {String} options.srcDown URL of image to use in 'down' state
+ * @param {String} [options.srcDown=null] URL of image to use in 'down' state.
- * @param {Element} [options.element] Element to use as a container for the
+ * @param {Number} [options.fadeDelay=0] How long to wait before fading.
- *  button.
+ * @param {Number} [options.fadeLength=2000] How long should it take to fade the button.
- * @property {String} tooltip Provides context help for the button we the
+ * @param {OpenSeadragon.EventHandler} [options.onPress=null] Event handler callback for {@link OpenSeadragon.Button.event:press}.
- *  user hovers over it.
+ * @param {OpenSeadragon.EventHandler} [options.onRelease=null] Event handler callback for {@link OpenSeadragon.Button.event:release}.
- * @property {String} srcRest URL of image to use in 'rest' state
+ * @param {OpenSeadragon.EventHandler} [options.onClick=null] Event handler callback for {@link OpenSeadragon.Button.event:click}.
- * @property {String} srcGroup URL of image to use in 'up' state
+ * @param {OpenSeadragon.EventHandler} [options.onEnter=null] Event handler callback for {@link OpenSeadragon.Button.event:enter}.
- * @property {String} srcHover URL of image to use in 'hover' state
+ * @param {OpenSeadragon.EventHandler} [options.onExit=null] Event handler callback for {@link OpenSeadragon.Button.event:exit}.
- * @property {String} srcDown URL of image to use in 'down' state
+ * @param {OpenSeadragon.EventHandler} [options.onFocus=null] Event handler callback for {@link OpenSeadragon.Button.event:focus}.
- * @property {Object} config Configurable settings for this button. DEPRECATED.
+ * @param {OpenSeadragon.EventHandler} [options.onBlur=null] Event handler callback for {@link OpenSeadragon.Button.event:blur}.
- * @property {Element} [element] Element to use as a container for the
- *  button.
- * @property {Number} fadeDelay How long to wait before fading
- * @property {Number} fadeLength How long should it take to fade the button.
- * @property {Number} fadeBeginTime When the button last began to fade.
- * @property {Boolean} shouldFade Whether this button should fade after user
- *  stops interacting with the viewport.
-    this.fadeDelay      = 0;      // begin fading immediately
-    this.fadeLength     = 2000;   // fade over a period of 2 seconds
-    this.fadeBeginTime  = null;
-    this.shouldFade     = false;
  */
 $.Button = function( options ) {
 
@@ -94,9 +93,17 @@ $.Button = function( options ) {
         srcDown:            null,
         clickTimeThreshold: $.DEFAULT_SETTINGS.clickTimeThreshold,
         clickDistThreshold: $.DEFAULT_SETTINGS.clickDistThreshold,
-        // begin fading immediately
+        /**
+         * How long to wait before fading.
+         * @member {Number} fadeDelay
+         * @memberof OpenSeadragon.Button#
+         */
         fadeDelay:          0,
-        // fade over a period of 2 seconds
+        /**
+         * How long should it take to fade the button.
+         * @member {Number} fadeLength
+         * @memberof OpenSeadragon.Button#
+         */
         fadeLength:         2000,
         onPress:            null,
         onRelease:          null,
@@ -108,6 +115,11 @@ $.Button = function( options ) {
 
     }, options );
 
+    /**
+     * The button element.
+     * @member {Element} element
+     * @memberof OpenSeadragon.Button#
+     */
     this.element        = options.element   || $.makeNeutralElement( "button" );
 
     //if the user has specified the element to bind the control to explicitly
@@ -159,15 +171,27 @@ $.Button = function( options ) {
     this.addHandler( "focus",     this.onFocus );
     this.addHandler( "blur",      this.onBlur );
 
+    /**
+     * The button's current state.
+     * @member {OpenSeadragon.ButtonState} currentState
+     * @memberof OpenSeadragon.Button#
+     */
     this.currentState = $.ButtonState.GROUP;
 
+    // When the button last began to fade.
     this.fadeBeginTime  = null;
+    // Whether this button should fade after user stops interacting with the viewport.
     this.shouldFade     = false;
 
     this.element.style.display  = "inline-block";
     this.element.style.position = "relative";
     this.element.title          = this.tooltip;
 
+    /**
+     * Tracks mouse/touch/key events on the button.
+     * @member {OpenSeadragon.MouseTracker} tracker
+     * @memberof OpenSeadragon.Button#
+     */
     this.tracker = new $.MouseTracker({
 
         element:            this.element,
@@ -177,6 +201,16 @@ $.Button = function( options ) {
         enterHandler: function( event ) {
             if ( event.insideElementPressed ) {
                 inTo( _this, $.ButtonState.DOWN );
+                /**
+                 * Raised when the cursor enters the Button element.
+                 *
+                 * @event enter
+                 * @memberof OpenSeadragon.Button
+                 * @type {object}
+                 * @property {OpenSeadragon.Button} eventSource - A reference to the Button which raised the event.
+                 * @property {Object} originalEvent - The original DOM event.
+                 * @property {?Object} userData - Arbitrary subscriber-defined object.
+                 */
                 _this.raiseEvent( "enter", { originalEvent: event.originalEvent } );
             } else if ( !event.buttonDownAny ) {
                 inTo( _this, $.ButtonState.HOVER );
@@ -185,29 +219,79 @@ $.Button = function( options ) {
 
         focusHandler: function ( event ) {
             this.enterHandler( event );
+            /**
+             * Raised when the Button element receives focus.
+             *
+             * @event focus
+             * @memberof OpenSeadragon.Button
+             * @type {object}
+             * @property {OpenSeadragon.Button} eventSource - A reference to the Button which raised the event.
+             * @property {Object} originalEvent - The original DOM event.
+             * @property {?Object} userData - Arbitrary subscriber-defined object.
+             */
             _this.raiseEvent( "focus", { originalEvent: event.originalEvent } );
         },
 
         exitHandler: function( event ) {
             outTo( _this, $.ButtonState.GROUP );
             if ( event.insideElementPressed ) {
+                /**
+                 * Raised when the cursor leaves the Button element.
+                 *
+                 * @event exit
+                 * @memberof OpenSeadragon.Button
+                 * @type {object}
+                 * @property {OpenSeadragon.Button} eventSource - A reference to the Button which raised the event.
+                 * @property {Object} originalEvent - The original DOM event.
+                 * @property {?Object} userData - Arbitrary subscriber-defined object.
+                 */
                 _this.raiseEvent( "exit", { originalEvent: event.originalEvent } );
             }
         },
 
         blurHandler: function ( event ) {
             this.exitHandler( event );
+            /**
+             * Raised when the Button element loses focus.
+             *
+             * @event blur
+             * @memberof OpenSeadragon.Button
+             * @type {object}
+             * @property {OpenSeadragon.Button} eventSource - A reference to the Button which raised the event.
+             * @property {Object} originalEvent - The original DOM event.
+             * @property {?Object} userData - Arbitrary subscriber-defined object.
+             */
             _this.raiseEvent( "blur", { originalEvent: event.originalEvent } );
         },
 
         pressHandler: function ( event ) {
             inTo( _this, $.ButtonState.DOWN );
+            /**
+             * Raised when a mouse button is pressed or touch occurs in the Button element.
+             *
+             * @event press
+             * @memberof OpenSeadragon.Button
+             * @type {object}
+             * @property {OpenSeadragon.Button} eventSource - A reference to the Button which raised the event.
+             * @property {Object} originalEvent - The original DOM event.
+             * @property {?Object} userData - Arbitrary subscriber-defined object.
+             */
             _this.raiseEvent( "press", { originalEvent: event.originalEvent } );
         },
 
         releaseHandler: function( event ) {
             if ( event.insideElementPressed && event.insideElementReleased ) {
                 outTo( _this, $.ButtonState.HOVER );
+                /**
+                 * Raised when the mouse button is released or touch ends in the Button element.
+                 *
+                 * @event release
+                 * @memberof OpenSeadragon.Button
+                 * @type {object}
+                 * @property {OpenSeadragon.Button} eventSource - A reference to the Button which raised the event.
+                 * @property {Object} originalEvent - The original DOM event.
+                 * @property {?Object} userData - Arbitrary subscriber-defined object.
+                 */
                 _this.raiseEvent( "release", { originalEvent: event.originalEvent } );
             } else if ( event.insideElementPressed ) {
                 outTo( _this, $.ButtonState.GROUP );
@@ -218,6 +302,16 @@ $.Button = function( options ) {
 
         clickHandler: function( event ) {
             if ( event.quick ) {
+                /**
+                 * Raised when a mouse button is pressed and released or touch is initiated and ended in the Button element within the time and distance threshold.
+                 *
+                 * @event click
+                 * @memberof OpenSeadragon.Button
+                 * @type {object}
+                 * @property {OpenSeadragon.Button} eventSource - A reference to the Button which raised the event.
+                 * @property {Object} originalEvent - The original DOM event.
+                 * @property {?Object} userData - Arbitrary subscriber-defined object.
+                 */
                 _this.raiseEvent("click", { originalEvent: event.originalEvent });
             }
         },
@@ -225,7 +319,27 @@ $.Button = function( options ) {
         keyHandler: function( event ){
             //console.log( "%s : handling key %s!", _this.tooltip, event.keyCode);
             if( 13 === event.keyCode ){
+                /***
+                 * Raised when a mouse button is pressed and released or touch is initiated and ended in the Button element within the time and distance threshold.
+                 *
+                 * @event click
+                 * @memberof OpenSeadragon.Button
+                 * @type {object}
+                 * @property {OpenSeadragon.Button} eventSource - A reference to the Button which raised the event.
+                 * @property {Object} originalEvent - The original DOM event.
+                 * @property {?Object} userData - Arbitrary subscriber-defined object.
+                 */
                 _this.raiseEvent( "click", { originalEvent: event.originalEvent } );
+                /***
+                 * Raised when the mouse button is released or touch ends in the Button element.
+                 *
+                 * @event release
+                 * @memberof OpenSeadragon.Button
+                 * @type {object}
+                 * @property {OpenSeadragon.Button} eventSource - A reference to the Button which raised the event.
+                 * @property {Object} originalEvent - The original DOM event.
+                 * @property {?Object} userData - Arbitrary subscriber-defined object.
+                 */
                 _this.raiseEvent( "release", { originalEvent: event.originalEvent } );
                 return false;
             }
@@ -237,13 +351,12 @@ $.Button = function( options ) {
     outTo( this, $.ButtonState.REST );
 };
 
-$.extend( $.Button.prototype, $.EventSource.prototype, {
+$.extend( $.Button.prototype, $.EventSource.prototype, /** @lends OpenSeadragon.Button.prototype */{
 
     /**
      * TODO: Determine what this function is intended to do and if it's actually
      * useful as an API point.
      * @function
-     * @name OpenSeadragon.Button.prototype.notifyGroupEnter
      */
     notifyGroupEnter: function() {
         inTo( this, $.ButtonState.GROUP );
@@ -253,18 +366,23 @@ $.extend( $.Button.prototype, $.EventSource.prototype, {
      * TODO: Determine what this function is intended to do and if it's actually
      * useful as an API point.
      * @function
-     * @name OpenSeadragon.Button.prototype.notifyGroupExit
      */
     notifyGroupExit: function() {
         outTo( this, $.ButtonState.REST );
     },
 
+    /**
+     * @function
+     */
     disable: function(){
         this.notifyGroupExit();
         this.element.disabled = true;
         $.setElementOpacity( this.element, 0.2, true );
     },
 
+    /**
+     * @function
+     */
     enable: function(){
         this.element.disabled = false;
         $.setElementOpacity( this.element, 1.0, true );

src/buttongroup.js

@@ -34,42 +34,41 @@
 
 (function( $ ){
 /**
- * Manages events on groups of buttons.
+ * @class ButtonGroup
- * @class
+ * @classdesc Manages events on groups of buttons.
- * @param {Object} options - a dictionary of settings applied against the entire
+ *
- * group of buttons
+ * @memberof OpenSeadragon
- * @param {Array}    options.buttons Array of buttons
+ * @param {Object} options - A dictionary of settings applied against the entire group of buttons.
- * @param {Element}  [options.group]   Element to use as the container,
+ * @param {Array} options.buttons Array of buttons
- * @param {Object}   options.config  Object with Viewer settings ( TODO: is
+ * @param {Element} [options.element] Element to use as the container
- *  this actually used anywhere? )
- * @param {Function} [options.enter]   Function callback for when the mouse
- *  enters group
- * @param {Function} [options.exit]    Function callback for when mouse leaves
- *  the group
- * @param {Function} [options.release] Function callback for when mouse is
- *  released
- * @property {Array} buttons - An array containing the buttons themselves.
- * @property {Element} element - The shared container for the buttons.
- * @property {Object} config - Configurable settings for the group of buttons.
- * @property {OpenSeadragon.MouseTracker} tracker - Tracks mouse events accross
- *  the group of buttons.
  **/
 $.ButtonGroup = function( options ) {
 
     $.extend( true, this, {
+        /**
+         * An array containing the buttons themselves.
+         * @member {Array} buttons
+         * @memberof OpenSeadragon.ButtonGroup#
+         */
         buttons:            [],
         clickTimeThreshold: $.DEFAULT_SETTINGS.clickTimeThreshold,
         clickDistThreshold: $.DEFAULT_SETTINGS.clickDistThreshold,
         labelText:          ""
     }, options );
 
-    // copy the botton elements
+    // copy the button elements  TODO: Why?
     var buttons = this.buttons.concat([]),
         _this = this,
         i;
 
+    /**
+     * The shared container for the buttons.
+     * @member {Element} element
+     * @memberof OpenSeadragon.ButtonGroup#
+     */
     this.element = options.element || $.makeNeutralElement( "fieldgroup" );
 
+    // TODO What if there IS an options.group specified? 
     if( !options.group ){
         this.label   = $.makeNeutralElement( "label" );
         //TODO: support labels for ButtonGroups
@@ -81,6 +80,11 @@ $.ButtonGroup = function( options ) {
         }
     }
 
+    /**
+     * Tracks mouse/touch/key events accross the group of buttons.
+     * @member {OpenSeadragon.MouseTracker} tracker
+     * @memberof OpenSeadragon.ButtonGroup#
+     */
     this.tracker = new $.MouseTracker({
         element:            this.element,
         clickTimeThreshold: this.clickTimeThreshold,
@@ -110,13 +114,13 @@ $.ButtonGroup = function( options ) {
     }).setTracking( true );
 };
 
-$.ButtonGroup.prototype = {
+$.ButtonGroup.prototype = /** @lends OpenSeadragon.ButtonGroup.prototype */{
 
     /**
      * TODO: Figure out why this is used on the public API and if a more useful
      * api can be created.
      * @function
-     * @name OpenSeadragon.ButtonGroup.prototype.emulateEnter
+     * @private
      */
     emulateEnter: function() {
         this.tracker.enterHandler( { eventSource: this.tracker } );
@@ -126,7 +130,7 @@ $.ButtonGroup.prototype = {
      * TODO: Figure out why this is used on the public API and if a more useful
      * api can be created.
      * @function
-     * @name OpenSeadragon.ButtonGroup.prototype.emulateExit
+     * @private
      */
     emulateExit: function() {
         this.tracker.exitHandler( { eventSource: this.tracker } );

src/control.js

@@ -35,10 +35,17 @@
 (function( $ ){
 
 /**
- * An enumeration of supported locations where controls can be anchored,
+ * An enumeration of supported locations where controls can be anchored.
- * including NONE, TOP_LEFT, TOP_RIGHT, BOTTOM_RIGHT, and BOTTOM_LEFT.
+ * The anchoring is always relative to the container.
- * The anchoring is always relative to the container
+ * @member ControlAnchor
+ * @memberof OpenSeadragon
  * @static
+ * @type {Object}
+ * @property {Number} NONE
+ * @property {Number} TOP_LEFT
+ * @property {Number} TOP_RIGHT
+ * @property {Number} BOTTOM_LEFT
+ * @property {Number} BOTTOM_RIGHT
  */
 $.ControlAnchor = {
     NONE: 0,
@@ -49,10 +56,12 @@ $.ControlAnchor = {
 };
 
 /**
- * A Control represents any interface element which is meant to allow the user
+ * @class Control
+ * @classdesc A Control represents any interface element which is meant to allow the user
  * to interact with the zoomable interface. Any control can be anchored to any
  * element.
- * @class
+ *
+ * @memberof OpenSeadragon
  * @param {Element} element - the control element to be anchored in the container.
  * @param {Object } options - All required and optional settings for configuring a control element.
  * @param {OpenSeadragon.ControlAnchor} [options.anchor=OpenSeadragon.ControlAnchor.NONE] - the position of the control
@@ -61,16 +70,6 @@ $.ControlAnchor = {
  *  directly to the container
  * @param {Boolean} [options.autoFade=true] - Whether the control should have the autofade behavior
  * @param {Element} container - the element to control will be anchored too.
- *
- * @property {Element} element - the element providing the user interface with
- *  some type of control. Eg a zoom-in button
- * @property {OpenSeadragon.ControlAnchor} anchor - the position of the control
- *  relative to the container.
- * @property {Boolean} autoFade - Whether the control should have the autofade behavior
- * @property {Element} container - the element within with the control is
- *  positioned.
- * @property {Element} wrapper - a neutral element surrounding the control
- *  element.
  */
 $.Control = function ( element, options, container ) {
     var parent = element.parentNode;
@@ -82,10 +81,35 @@ $.Control = function ( element, options, container ) {
          options = {anchor: options};
     }
     options.attachToViewer = (typeof options.attachToViewer === 'undefined') ? true : options.attachToViewer;
+    /**
+     * True if the control should have autofade behavior.
+     * @member {Boolean} autoFade
+     * @memberof OpenSeadragon.Control#
+     */
     this.autoFade = (typeof options.autoFade === 'undefined') ? true : options.autoFade;
+    /**
+     * The element providing the user interface with some type of control (e.g. a zoom-in button).
+     * @member {Element} element
+     * @memberof OpenSeadragon.Control#
+     */
     this.element    = element;
+    /**
+     * The position of the Control relative to its container.
+     * @member {OpenSeadragon.ControlAnchor} anchor
+     * @memberof OpenSeadragon.Control#
+     */
     this.anchor     = options.anchor;
+    /**
+     * The Control's containing element.
+     * @member {Element} container
+     * @memberof OpenSeadragon.Control#
+     */
     this.container  = container;
+    /**
+     * A neutral element surrounding the control element.
+     * @member {Element} wrapper
+     * @memberof OpenSeadragon.Control#
+     */
     this.wrapper    = $.makeNeutralElement( "span" );
     this.wrapper.style.display = "inline-block";
     this.wrapper.appendChild( this.element );
@@ -110,7 +134,7 @@ $.Control = function ( element, options, container ) {
     }
 };
 
-$.Control.prototype = {
+$.Control.prototype = /** @lends OpenSeadragon.Control.prototype */{
 
     /**
      * Removes the control from the container.

src/controldock.js

@@ -34,7 +34,10 @@
 
 (function( $ ){
     /**
-     * @class
+     * @class ControlDock
+     * @classdesc Provides a container element (a <form> element) with support for the layout of control elements.
+     *
+     * @memberof OpenSeadragon
      */
     $.ControlDock = function( options ){
         var layouts = [ 'topleft', 'topright', 'bottomright', 'bottomleft'],
@@ -85,7 +88,7 @@
         this.container.appendChild( this.controls.bottomleft );
     };
 
-    $.ControlDock.prototype = {
+    $.ControlDock.prototype = /** @lends OpenSeadragon.ControlDock.prototype */{
 
         /**
          * @function

src/displayrectangle.js

@@ -35,10 +35,12 @@
 (function( $ ){
 
 /**
- * A display rectanlge is very similar to the OpenSeadragon.Rect but adds two
+ * @class DisplayRect
+ * @classdesc A display rectangle is very similar to {@link OpenSeadragon.Rect} but adds two
  * fields, 'minLevel' and 'maxLevel' which denote the supported zoom levels
  * for this rectangle.
- * @class
+ *
+ * @memberof OpenSeadragon
  * @extends OpenSeadragon.Rect
  * @param {Number} x The vector component 'x'.
  * @param {Number} y The vector component 'y'.
@@ -46,13 +48,21 @@
  * @param {Number} height The vector component 'width'.
  * @param {Number} minLevel The lowest zoom level supported.
  * @param {Number} maxLevel The highest zoom level supported.
- * @property {Number} minLevel The lowest zoom level supported.
- * @property {Number} maxLevel The highest zoom level supported.
  */
 $.DisplayRect = function( x, y, width, height, minLevel, maxLevel ) {
     $.Rect.apply( this, [ x, y, width, height ] );
 
+    /**
+     * The lowest zoom level supported.
+     * @member {Number} minLevel
+     * @memberof OpenSeadragon.DisplayRect#
+     */
     this.minLevel = minLevel;
+    /**
+     * The highest zoom level supported.
+     * @member {Number} maxLevel
+     * @memberof OpenSeadragon.DisplayRect#
+     */
     this.maxLevel = maxLevel;
 };
 

src/drawer.js

@@ -48,27 +48,14 @@ var DEVICE_SCREEN       = $.getWindowSize(),
 
 
 /**
- * @class
+ * @class Drawer
+ * @classdesc Handles rendering of tiles for an {@link OpenSeadragon.Viewer}. 
+ * A new instance is created for each TileSource opened (see {@link OpenSeadragon.Viewer#drawer}).
+ *
+ * @memberof OpenSeadragon
  * @param {OpenSeadragon.TileSource} source - Reference to Viewer tile source.
  * @param {OpenSeadragon.Viewport} viewport - Reference to Viewer viewport.
- * @param {Element} element - Reference to Viewer 'canvas'.
+ * @param {Element} element - Parent element.
- * @property {OpenSeadragon.TileSource} source - Reference to Viewer tile source.
- * @property {OpenSeadragon.Viewport} viewport - Reference to Viewer viewport.
- * @property {Element} container - Reference to Viewer 'canvas'.
- * @property {Element|Canvas} canvas - TODO
- * @property {CanvasContext} context - TODO
- * @property {Object} config - Reference to Viewer config.
- * @property {Number} downloading - How many images are currently being loaded in parallel.
- * @property {Number} normHeight - Ratio of zoomable image height to width.
- * @property {Object} tilesMatrix - A '3d' dictionary [level][x][y] --> Tile.
- * @property {Array} tilesLoaded - An unordered list of Tiles with loaded images.
- * @property {Object} coverage - A '3d' dictionary [level][x][y] --> Boolean.
- * @property {Array} overlays - An unordered list of Overlays added.
- * @property {Array} lastDrawn - An unordered list of Tiles drawn last frame.
- * @property {Number} lastResetTime - Last time for which the drawer was reset.
- * @property {Boolean} midUpdate - Is the drawer currently updating the viewport?
- * @property {Boolean} updateAgain - Does the drawer need to update the viewort again?
- * @property {Element} element - DEPRECATED Alias for container.
  */
 $.Drawer = function( options ) {
 
@@ -79,9 +66,9 @@ $.Drawer = function( options ) {
 
     if( !$.isPlainObject( options ) ){
         options = {
-            source:     args[ 0 ],
+            source:     args[ 0 ], // Reference to Viewer tile source.
-            viewport:   args[ 1 ],
+            viewport:   args[ 1 ], // Reference to Viewer viewport.
-            element:    args[ 2 ]
+            element:    args[ 2 ]  // Parent element.
         };
     }
 
@@ -89,18 +76,18 @@ $.Drawer = function( options ) {
 
         //internal state properties
         viewer:         null,
-        downloading:    0,
+        downloading:    0,     // How many images are currently being loaded in parallel.
-        tilesMatrix:    {},
+        tilesMatrix:    {},    // A '3d' dictionary [level][x][y] --> Tile.
-        tilesLoaded:    [],
+        tilesLoaded:    [],    // An unordered list of Tiles with loaded images.
-        coverage:       {},
+        coverage:       {},    // A '3d' dictionary [level][x][y] --> Boolean.
-        lastDrawn:      [],
+        lastDrawn:      [],    // An unordered list of Tiles drawn last frame.
-        lastResetTime:  0,
+        lastResetTime:  0,     // Last time for which the drawer was reset.
-        midUpdate:      false,
+        midUpdate:      false, // Is the drawer currently updating the viewport?
-        updateAgain:    true,
+        updateAgain:    true,  // Does the drawer need to update the viewort again?
 
 
         //internal state / configurable settings
-        overlays:           [],
+        overlays:           [], // An unordered list of Overlays added.
         collectionOverlays: {},
 
         //configurable settings
@@ -119,10 +106,33 @@ $.Drawer = function( options ) {
     }, options );
 
     this.useCanvas  = $.supportsCanvas && ( this.viewer ? this.viewer.useCanvas : true );
+    /**
+     * The parent element of this Drawer instance, passed in when the Drawer was created.
+     * The parent of {@link OpenSeadragon.Drawer#canvas}.
+     * @member {Element} container
+     * @memberof OpenSeadragon.Drawer#
+     */
     this.container  = $.getElement( this.element );
+    /**
+     * A <canvas> element if the browser supports them, otherwise a <div> element.
+     * Child element of {@link OpenSeadragon.Drawer#container}.
+     * @member {Element} canvas
+     * @memberof OpenSeadragon.Drawer#
+     */
     this.canvas     = $.makeNeutralElement( this.useCanvas ? "canvas" : "div" );
+    /**
+     * 2d drawing context for {@link OpenSeadragon.Drawer#canvas} if it's a <canvas> element, otherwise null.
+     * @member {Object} context
+     * @memberof OpenSeadragon.Drawer#
+     */
     this.context    = this.useCanvas ? this.canvas.getContext( "2d" ) : null;
+    // Ratio of zoomable image height to width.
     this.normHeight = this.source.dimensions.y / this.source.dimensions.x;
+    /**
+     * @member {Element} element
+     * @memberof OpenSeadragon.Drawer#
+     * @deprecated Alias for {@link OpenSeadragon.Drawer#container}.
+     */
     this.element    = this.container;
 
     // We force our container to ltr because our drawing math doesn't work in rtl.
@@ -153,7 +163,7 @@ $.Drawer = function( options ) {
     //this.profiler    = new $.Profiler();
 };
 
-$.Drawer.prototype = {
+$.Drawer.prototype = /** @lends OpenSeadragon.Drawer.prototype */{
 
     /**
      * Adds an html element as an overlay to the current viewport.  Useful for
@@ -170,6 +180,7 @@ $.Drawer.prototype = {
      * @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
      */
     addOverlay: function( element, location, placement, onDraw ) {
         var options;
@@ -199,6 +210,18 @@ $.Drawer.prototype = {
         }) );
         this.updateAgain = true;
         if( this.viewer ){
+            /**
+             * Raised when an overlay is added to the viewer (see {@link OpenSeadragon.Drawer#addOverlay}).
+             *
+             * @event add-overlay
+             * @memberof OpenSeadragon.Viewer
+             * @type {object}
+             * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event.
+             * @property {Element} element - The overlay element.
+             * @property {OpenSeadragon.Point|OpenSeadragon.Rect} location
+             * @property {OpenSeadragon.OverlayPlacement} placement
+             * @property {?Object} userData - Arbitrary subscriber-defined object.
+             */
             this.viewer.raiseEvent( 'add-overlay', {
                 element: element,
                 location: options.location,
@@ -218,6 +241,7 @@ $.Drawer.prototype = {
      *      viewport which the location coordinates will be treated as relative
      *      to.
      * @return {OpenSeadragon.Drawer} Chainable.
+     * @fires OpenSeadragon.Viewer.event:update-overlay
      */
     updateOverlay: function( element, location, placement ) {
         var i;
@@ -230,6 +254,18 @@ $.Drawer.prototype = {
             this.updateAgain = true;
         }
         if( this.viewer ){
+            /**
+             * Raised when an overlay's location or placement changes (see {@link OpenSeadragon.Drawer#updateOverlay}).
+             *
+             * @event update-overlay
+             * @memberof OpenSeadragon.Viewer
+             * @type {object}
+             * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event.
+             * @property {Element} element
+             * @property {OpenSeadragon.Point|OpenSeadragon.Rect} location
+             * @property {OpenSeadragon.OverlayPlacement} placement
+             * @property {?Object} userData - Arbitrary subscriber-defined object.
+             */
             this.viewer.raiseEvent( 'update-overlay', {
                 element: element,
                 location: location,
@@ -246,6 +282,7 @@ $.Drawer.prototype = {
      * @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
      */
     removeOverlay: function( element ) {
         var i;
@@ -259,6 +296,16 @@ $.Drawer.prototype = {
             this.updateAgain = true;
         }
         if( this.viewer ){
+            /**
+             * Raised when an overlay is removed from the viewer (see {@link OpenSeadragon.Drawer#removeOverlay}).
+             *
+             * @event remove-overlay
+             * @memberof OpenSeadragon.Viewer
+             * @type {object}
+             * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event.
+             * @property {Element} element - The overlay element.
+             * @property {?Object} userData - Arbitrary subscriber-defined object.
+             */
             this.viewer.raiseEvent( 'remove-overlay', {
                 element: element
             });
@@ -271,6 +318,7 @@ $.Drawer.prototype = {
      *      and update.
      * @method
      * @return {OpenSeadragon.Drawer} Chainable.
+     * @fires OpenSeadragon.Viewer.event:clear-overlay
      */
     clearOverlays: function() {
         while ( this.overlays.length > 0 ) {
@@ -278,6 +326,15 @@ $.Drawer.prototype = {
             this.updateAgain = true;
         }
         if( this.viewer ){
+            /**
+             * Raised when all overlays are removed from the viewer (see {@link OpenSeadragon.Drawer#clearOverlays}).
+             *
+             * @event clear-overlay
+             * @memberof OpenSeadragon.Viewer
+             * @type {object}
+             * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event.
+             * @property {?Object} userData - Arbitrary subscriber-defined object.
+             */
             this.viewer.raiseEvent( 'clear-overlay', {} );
         }
         return this;
@@ -399,6 +456,11 @@ $.Drawer.prototype = {
         return loading;
     },
 
+    /**
+     * Returns whether rotation is supported or not.
+     * @method
+     * @return {Boolean} True if rotation is supported.
+     */
     canRotate: function() {
         return this.useCanvas;
     }
@@ -471,6 +533,15 @@ function updateViewport( drawer ) {
     drawer.updateAgain = false;
 
     if( drawer.viewer ){
+        /**
+         * <em>- Needs documentation -</em>
+         *
+         * @event update-viewport
+         * @memberof OpenSeadragon.Viewer
+         * @type {object}
+         * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event.
+         * @property {?Object} userData - Arbitrary subscriber-defined object.
+         */
         drawer.viewer.raiseEvent( 'update-viewport', {} );
     }
 
@@ -645,6 +716,23 @@ function updateLevel( drawer, haveDrawn, drawLevel, level, levelOpacity, levelVi
 
 
     if( drawer.viewer ){
+        /**
+         * <em>- Needs documentation -</em>
+         *
+         * @event update-level
+         * @memberof OpenSeadragon.Viewer
+         * @type {object}
+         * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event.
+         * @property {Object} havedrawn
+         * @property {Object} level
+         * @property {Object} opacity
+         * @property {Object} visibility
+         * @property {Object} topleft
+         * @property {Object} bottomright
+         * @property {Object} currenttime
+         * @property {Object} best
+         * @property {?Object} userData - Arbitrary subscriber-defined object.
+         */
         drawer.viewer.raiseEvent( 'update-level', {
             havedrawn: haveDrawn,
             level: level,
@@ -708,6 +796,16 @@ function updateTile( drawer, drawLevel, haveDrawn, x, y, level, levelOpacity, le
         drawTile = drawLevel;
 
     if( drawer.viewer ){
+        /**
+         * <em>- Needs documentation -</em>
+         *
+         * @event update-tile
+         * @memberof OpenSeadragon.Viewer
+         * @type {object}
+         * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event.
+         * @property {OpenSeadragon.Tile} tile
+         * @property {?Object} userData - Arbitrary subscriber-defined object.
+         */
         drawer.viewer.raiseEvent( 'update-tile', {
             tile: tile
         });
@@ -1222,6 +1320,16 @@ function drawTiles( drawer, lastDrawn ){
         }
 
         if( drawer.viewer ){
+            /**
+             * <em>- Needs documentation -</em>
+             *
+             * @event tile-drawn
+             * @memberof OpenSeadragon.Viewer
+             * @type {object}
+             * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event.
+             * @property {OpenSeadragon.Tile} tile
+             * @property {?Object} userData - Arbitrary subscriber-defined object.
+             */
             drawer.viewer.raiseEvent( 'tile-drawn', {
                 tile: tile
             });

src/dzitilesource.js

@@ -35,7 +35,8 @@
 (function( $ ){
 
 /**
- * @class
+ * @class DziTileSource
+ * @memberof OpenSeadragon
  * @extends OpenSeadragon.TileSource
  * @param {Number|Object} width - the pixel width of the image or the idiomatic
  *      options object which is used instead of positional arguments.
@@ -92,14 +93,13 @@ $.DziTileSource = function( width, height, tileSize, tileOverlap, tilesUrl, file
 
 };
 
-$.extend( $.DziTileSource.prototype, $.TileSource.prototype, {
+$.extend( $.DziTileSource.prototype, $.TileSource.prototype, /** @lends OpenSeadragon.DziTileSource.prototype */{
 
 
     /**
      * Determine if the data and/or url imply the image service is supported by
      * this tile source.
      * @function
-     * @name OpenSeadragon.DziTileSource.prototype.supports
      * @param {Object|Array} data
      * @param {String} optional - url
      */
@@ -118,7 +118,6 @@ $.extend( $.DziTileSource.prototype, $.TileSource.prototype, {
     /**
      *
      * @function
-     * @name OpenSeadragon.DziTileSource.prototype.configure
      * @param {Object|XMLDocument} data - the raw configuration
      * @param {String} url - the url the data was retreived from if any.
      * @return {Object} options - A dictionary of keyword arguments sufficient
@@ -147,7 +146,6 @@ $.extend( $.DziTileSource.prototype, $.TileSource.prototype, {
 
     /**
      * @function
-     * @name OpenSeadragon.DziTileSource.prototype.getTileUrl
      * @param {Number} level
      * @param {Number} x
      * @param {Number} y
@@ -159,7 +157,6 @@ $.extend( $.DziTileSource.prototype, $.TileSource.prototype, {
 
     /**
      * @function
-     * @name OpenSeadragon.DziTileSource.prototype.tileExists
      * @param {Number} level
      * @param {Number} x
      * @param {Number} y

src/eventsource.js

@@ -35,22 +35,33 @@
 (function($){
 
 /**
- * For use by classes which want to support custom, non-browser events.
+ * Event handler method signature used by all OpenSeadragon events.
- * TODO: Add a method 'one' which automatically unbinds a listener after 
+ *
- *       the first triggered event that matches.
+ * @callback EventHandler
- * @class
+ * @memberof OpenSeadragon
+ * @param {Object} event - See individual events for event-specific properties.
+ */
+
+
+/**
+ * @class EventSource
+ * @classdesc For use by classes which want to support custom, non-browser events.
+ *
+ * @memberof OpenSeadragon
  */
 $.EventSource = function() {
     this.events = {};
 };
 
-$.EventSource.prototype = {
+$.EventSource.prototype = /** @lends OpenSeadragon.EventSource.prototype */{
+
+    // TODO: Add a method 'one' which automatically unbinds a listener after the first triggered event that matches.
 
     /**
      * Add an event handler for a given event.
      * @function
      * @param {String} eventName - Name of event to register.
-     * @param {Function} handler - Function to call when event is triggered.
+     * @param {OpenSeadragon.EventHandler} handler - Function to call when event is triggered.
      * @param {Object} [userData=null] - Arbitrary object to be passed unchanged to the handler.
      */
     addHandler: function ( eventName, handler, userData ) {
@@ -67,7 +78,7 @@ $.EventSource.prototype = {
      * Remove a specific event handler for a given event.
      * @function
      * @param {String} eventName - Name of event for which the handler is to be removed.
-     * @param {Function} handler - Function to be removed.
+     * @param {OpenSeadragon.EventHandler} handler - Function to be removed.
      */
     removeHandler: function ( eventName, handler ) {
         var events = this.events[ eventName ],
@@ -104,7 +115,7 @@ $.EventSource.prototype = {
     },
 
     /**
-     * Retrive the list of all handlers registered for a given event.
+     * Get a function which iterates the list of all handlers registered for a given event, calling the handler for each.
      * @function
      * @param {String} eventName - Name of event to get handlers for.
      */
@@ -133,7 +144,7 @@ $.EventSource.prototype = {
      * Trigger an event, optionally passing additional information.
      * @function
      * @param {String} eventName - Name of event to register.
-     * @param {Function} handler - Function to call when event is triggered.
+     * @param {Object} eventArgs - Event-specific data.
      */
     raiseEvent: function( eventName, eventArgs ) {
         //uncomment if you want to get a log of all events

src/fullscreen.js

@@ -60,12 +60,20 @@
  */
 
 
-/**
- * Determines the appropriate level of native full screen support we can get
- * from the browser.
- * @name $.supportsFullScreen
- */
 (function( $ ) {
+    /**
+     * Determined native full screen support we can get from the browser.
+     * @member fullScreenApi
+     * @memberof OpenSeadragon
+     * @type {object}
+     * @property {Boolean} supportsFullScreen
+     * @property {Function} isFullScreen
+     * @property {Function} requestFullScreen
+     * @property {Function} cancelFullScreen
+     * @property {String} fullScreenEventName
+     * @property {String} fullScreenErrorEventName
+     * @property {String} prefix
+     */
     var fullScreenApi = {
             supportsFullScreen: false,
             isFullScreen: function() { return false; },

src/iiif1_1tilesource.js

@@ -35,11 +35,11 @@
 (function( $ ){
 
 /**
- * A client implementation of the International Image Interoperability
+ * @class IIIF1_1TileSource
- * Format: Image API 1.1 - Please read more about the specification
+ * @classdesc A client implementation of the International Image Interoperability
- * at
+ * Format: Image API 1.1
  *
- * @class
+ * @memberof OpenSeadragon
  * @extends OpenSeadragon.TileSource
  * @see http://library.stanford.edu/iiif/image-api/
  */
@@ -74,12 +74,11 @@ $.IIIF1_1TileSource = function( options ){
     $.TileSource.apply( this, [ options ] );
 };
 
-$.extend( $.IIIF1_1TileSource.prototype, $.TileSource.prototype, {
+$.extend( $.IIIF1_1TileSource.prototype, $.TileSource.prototype, /** @lends OpenSeadragon.IIIF1_1TileSource.prototype */{
     /**
      * Determine if the data and/or url imply the image service is supported by
      * this tile source.
      * @function
-     * @name OpenSeadragon.IIIF1_1TileSource.prototype.supports
      * @param {Object|Array} data
      * @param {String} optional - url
      */
@@ -95,7 +94,6 @@ $.extend( $.IIIF1_1TileSource.prototype, $.TileSource.prototype, {
     /**
      *
      * @function
-     * @name OpenSeadragon.IIIF1_1TileSource.prototype.configure
      * @param {Object} data - the raw configuration
      */
     // IIIF 1.1 Info Looks like this (XML syntax is no more):
@@ -118,7 +116,6 @@ $.extend( $.IIIF1_1TileSource.prototype, $.TileSource.prototype, {
      * Responsible for retreiving the url which will return an image for the
      * region specified by the given x, y, and level components.
      * @function
-     * @name OpenSeadragon.IIIF1_1TileSource.prototype.getTileUrl
      * @param {Number} level - z index
      * @param {Number} x
      * @param {Number} y

src/iiiftilesource.js

@@ -42,11 +42,11 @@
 (function( $ ){
 
 /**
- * A client implementation of the International Image Interoperability
+ * @class IIIFTileSource
- * Format: Image API Draft 0.2 - Please read more about the specification
+ * @classdesc A client implementation of the International Image Interoperability
- * at
+ * Format: Image API Draft 0.2
  *
- * @class
+ * @memberof OpenSeadragon
  * @extends OpenSeadragon.TileSource
  * @see http://library.stanford.edu/iiif/image-api/
  */
@@ -81,12 +81,11 @@ $.IIIFTileSource = function( options ){
     $.TileSource.apply( this, [ options ] );
 };
 
-$.extend( $.IIIFTileSource.prototype, $.TileSource.prototype, {
+$.extend( $.IIIFTileSource.prototype, $.TileSource.prototype, /** @lends OpenSeadragon.IIIFTileSource.prototype */{
     /**
      * Determine if the data and/or url imply the image service is supported by
      * this tile source.
-     * @function
+     * @method
-     * @name OpenSeadragon.IIIFTileSource.prototype.supports
      * @param {Object|Array} data
      * @param {String} optional - url
      */
@@ -109,10 +108,9 @@ $.extend( $.IIIFTileSource.prototype, $.TileSource.prototype, {
         );
     },
 
-    /**
+   /**
      *
-     * @function
+     * @method
-     * @name OpenSeadragon.IIIFTileSource.prototype.configure
      * @param {Object|XMLDocument} data - the raw configuration
      * @param {String} url - the url the data was retreived from if any.
      * @return {Object} options - A dictionary of keyword arguments sufficient
@@ -152,8 +150,7 @@ $.extend( $.IIIFTileSource.prototype, $.TileSource.prototype, {
     /**
      * Responsible for retreiving the url which will return an image for the
      * region speified by the given x, y, and level components.
-     * @function
+     * @method
-     * @name OpenSeadragon.IIIFTileSource.prototype.getTileUrl
      * @param {Number} level - z index
      * @param {Number} x
      * @param {Number} y
@@ -215,28 +212,28 @@ $.extend( $.IIIFTileSource.prototype, $.TileSource.prototype, {
  * @private
  * @inner
  * @function
- *
+ * @example
-    <?xml version="1.0" encoding="UTF-8"?>
+ *   <?xml version="1.0" encoding="UTF-8"?>
-    <info xmlns="http://library.stanford.edu/iiif/image-api/ns/">
+ *   <info xmlns="http://library.stanford.edu/iiif/image-api/ns/">
-      <identifier>1E34750D-38DB-4825-A38A-B60A345E591C</identifier>
+ *     <identifier>1E34750D-38DB-4825-A38A-B60A345E591C</identifier>
-      <width>6000</width>
+ *     <width>6000</width>
-      <height>4000</height>
+ *     <height>4000</height>
-      <scale_factors>
+ *     <scale_factors>
-        <scale_factor>1</scale_factor>
+ *       <scale_factor>1</scale_factor>
-        <scale_factor>2</scale_factor>
+ *       <scale_factor>2</scale_factor>
-        <scale_factor>4</scale_factor>
+ *       <scale_factor>4</scale_factor>
-      </scale_factors>
+ *     </scale_factors>
-      <tile_width>1024</tile_width>
+ *     <tile_width>1024</tile_width>
-      <tile_height>1024</tile_height>
+ *     <tile_height>1024</tile_height>
-      <formats>
+ *     <formats>
-        <format>jpg</format>
+ *       <format>jpg</format>
-        <format>png</format>
+ *       <format>png</format>
-      </formats>
+ *     </formats>
-      <qualities>
+ *     <qualities>
-        <quality>native</quality>
+ *       <quality>native</quality>
-        <quality>grey</quality>
+ *       <quality>grey</quality>
-      </qualities>
+ *     </qualities>
-    </info>
+ *   </info>
  */
 function configureFromXml( tileSource, xmlDoc ){
 
@@ -306,18 +303,18 @@ function parseXML( node, configuration, property ){
  * @private
  * @inner
  * @function
- *
+ * @example
-    {
+ *   {
-        "profile" : "http://library.stanford.edu/iiif/image-api/compliance.html#level1",
+ *       "profile" : "http://library.stanford.edu/iiif/image-api/compliance.html#level1",
-        "identifier" : "1E34750D-38DB-4825-A38A-B60A345E591C",
+ *       "identifier" : "1E34750D-38DB-4825-A38A-B60A345E591C",
-        "width" : 6000,
+ *       "width" : 6000,
-        "height" : 4000,
+ *       "height" : 4000,
-        "scale_factors" : [ 1, 2, 4 ],
+ *       "scale_factors" : [ 1, 2, 4 ],
-        "tile_width" : 1024,
+ *       "tile_width" : 1024,
-        "tile_height" : 1024,
+ *       "tile_height" : 1024,
-        "formats" : [ "jpg", "png" ],
+ *       "formats" : [ "jpg", "png" ],
-        "quality" : [ "native", "grey" ]
+ *       "quality" : [ "native", "grey" ]
-    }
+ *   }
  */
 function configureFromObject( tileSource, configuration ){
     //the image_host property is not part of the iiif standard but is included here to

src/legacytilesource.js

@@ -35,13 +35,15 @@
 (function( $ ){
 
 /**
- * The LegacyTileSource allows simple, traditional image pyramids to be loaded
+ * @class LegacyTileSource
+ * @classdesc The LegacyTileSource allows simple, traditional image pyramids to be loaded
  * into an OpenSeadragon Viewer.  Basically, this translates to the historically
  * common practice of starting with a 'master' image, maybe a tiff for example,
  * and generating a set of 'service' images like one or more thumbnails, a medium
  * resolution image and a high resolution image in standard web formats like
  * png or jpg.
- * @class
+ *
+ * @memberof OpenSeadragon
  * @extends OpenSeadragon.TileSource
  * @param {Array} levels An array of file descriptions, each is an object with
  *      a 'url', a 'width', and a 'height'.  Overriding classes can expect more
@@ -96,12 +98,11 @@ $.LegacyTileSource = function( levels ) {
     this.levels = options.levels;
 };
 
-$.extend( $.LegacyTileSource.prototype, $.TileSource.prototype, {
+$.extend( $.LegacyTileSource.prototype, $.TileSource.prototype, /** @lends OpenSeadragon.LegacyTileSource.prototype */{
     /**
      * Determine if the data and/or url imply the image service is supported by
      * this tile source.
      * @function
-     * @name OpenSeadragon.LegacyTileSource.prototype.supports
      * @param {Object|Array} data
      * @param {String} optional - url
      */
@@ -119,7 +120,6 @@ $.extend( $.LegacyTileSource.prototype, $.TileSource.prototype, {
     /**
      *
      * @function
-     * @name OpenSeadragon.LegacyTileSource.prototype.configure
      * @param {Object|XMLDocument} configuration - the raw configuration
      * @param {String} dataUrl - the url the data was retreived from if any.
      * @return {Object} options - A dictionary of keyword arguments sufficient
@@ -144,7 +144,6 @@ $.extend( $.LegacyTileSource.prototype, $.TileSource.prototype, {
 
     /**
      * @function
-     * @name OpenSeadragon.LegacyTileSource.prototype.getLevelScale
      * @param {Number} level
      */
     getLevelScale: function ( level ) {
@@ -159,7 +158,6 @@ $.extend( $.LegacyTileSource.prototype, $.TileSource.prototype, {
 
     /**
      * @function
-     * @name OpenSeadragon.LegacyTileSource.prototype.getNumTiles
      * @param {Number} level
      */
     getNumTiles: function( level ) {
@@ -173,7 +171,6 @@ $.extend( $.LegacyTileSource.prototype, $.TileSource.prototype, {
 
     /**
      * @function
-     * @name OpenSeadragon.LegacyTileSource.prototype.getTileAtPoint
      * @param {Number} level
      * @param {OpenSeadragon.Point} point
      */
@@ -188,7 +185,6 @@ $.extend( $.LegacyTileSource.prototype, $.TileSource.prototype, {
      * server technologies, and various specifications for building image
      * pyramids, this method is here to allow easy integration.
      * @function
-     * @name OpenSeadragon.LegacyTileSource.prototype.getTileUrl
      * @param {Number} level
      * @param {Number} x
      * @param {Number} y

src/mousetracker.js

@@ -46,17 +46,19 @@
         THIS           = {};
 
     /**
-     * The MouseTracker allows other classes to set handlers for common mouse
+     * @class MouseTracker
-     * events on a specific element like, 'enter', 'exit', 'press', 'release',
+     * @classdesc Provides simplified handling of common mouse, touch, and keyboard
+     * events on a specific element, like 'enter', 'exit', 'press', 'release',
      * 'scroll', 'click', and 'drag'.
-     * @class
+     *
+     * @memberof OpenSeadragon
      * @param {Object} options
      *      Allows configurable properties to be entirely specified by passing
      *      an options object to the constructor.  The constructor also supports
-     *      the original positional arguments 'elements', 'clickTimeThreshold',
+     *      the original positional arguments 'element', 'clickTimeThreshold',
      *      and 'clickDistThreshold' in that order.
      * @param {Element|String} options.element
-     *      A reference to an element or an element id for which the mouse
+     *      A reference to an element or an element id for which the mouse/touch/key
      *      events will be monitored.
      * @param {Number} options.clickTimeThreshold
      *      The number of milliseconds within which multiple mouse clicks
@@ -64,43 +66,33 @@
      * @param {Number} options.clickDistThreshold
      *      The distance between mouse click within multiple mouse clicks
      *      will be treated as a single event.
-     * @param {Number} options.stopDelay
+     * @param {Number} [options.stopDelay=50]
      *      The number of milliseconds without mouse move before the mouse stop
      *      event is fired.
-     * @param {Function} options.enterHandler
+     * @param {OpenSeadragon.EventHandler} [options.enterHandler=null]
      *      An optional handler for mouse enter.
-     * @param {Function} options.exitHandler
+     * @param {OpenSeadragon.EventHandler} [options.exitHandler=null]
      *      An optional handler for mouse exit.
-     * @param {Function} options.pressHandler
+     * @param {OpenSeadragon.EventHandler} [options.pressHandler=null]
      *      An optional handler for mouse press.
-     * @param {Function} options.releaseHandler
+     * @param {OpenSeadragon.EventHandler} [options.releaseHandler=null]
      *      An optional handler for mouse release.
-     * @param {Function} options.moveHandler
+     * @param {OpenSeadragon.EventHandler} [options.moveHandler=null]
      *      An optional handler for mouse move.
-     * @param {Function} options.scrollHandler
+     * @param {OpenSeadragon.EventHandler} [options.scrollHandler=null]
      *      An optional handler for mouse scroll.
-     * @param {Function} options.clickHandler
+     * @param {OpenSeadragon.EventHandler} [options.clickHandler=null]
      *      An optional handler for mouse click.
-     * @param {Function} options.dragHandler
+     * @param {OpenSeadragon.EventHandler} [options.dragHandler=null]
      *      An optional handler for mouse drag.
-     * @param {Function} options.keyHandler
+     * @param {OpenSeadragon.EventHandler} [options.keyHandler=null]
      *      An optional handler for keypress.
-     * @param {Function} options.focusHandler
+     * @param {OpenSeadragon.EventHandler} [options.focusHandler=null]
      *      An optional handler for focus.
-     * @param {Function} options.blurHandler
+     * @param {OpenSeadragon.EventHandler} [options.blurHandler=null]
      *      An optional handler for blur.
      * @param {Object} [options.userData=null]
      *      Arbitrary object to be passed unchanged to any attached handler methods.
-     * @property {Number} hash
-     *      An unique hash for this tracker.
-     * @property {Element} element
-     *      The element for which mouse event are being monitored.
-     * @property {Number} clickTimeThreshold
-     *      The number of milliseconds within which mutliple mouse clicks
-     *      will be treated as a single event.
-     * @property {Number} clickDistThreshold
-     *      The distance between mouse click within multiple mouse clicks
-     *      will be treated as a single event.
      */
     $.MouseTracker = function ( options ) {
 
@@ -114,9 +106,24 @@
             };
         }
 
-        this.hash               = Math.random();
+        this.hash               = Math.random(); // An unique hash for this tracker.
+        /**
+         * The element for which mouse/touch/key events are being monitored.
+         * @member {Element} element
+         * @memberof OpenSeadragon.MouseTracker#
+         */
         this.element            = $.getElement( options.element );
+        /**
+         * The number of milliseconds within which mutliple mouse clicks will be treated as a single event.
+         * @member {Number} clickTimeThreshold
+         * @memberof OpenSeadragon.MouseTracker#
+         */
         this.clickTimeThreshold = options.clickTimeThreshold;
+        /**
+         * The distance between mouse click within multiple mouse clicks will be treated as a single event.
+         * @member {Number} clickDistThreshold
+         * @memberof OpenSeadragon.MouseTracker#
+         */
         this.clickDistThreshold = options.clickDistThreshold;
         this.userData           = options.userData       || null;
         this.stopDelay          = options.stopDelay      || 50;
@@ -188,7 +195,7 @@
 
     };
 
-    $.MouseTracker.prototype = {
+    $.MouseTracker.prototype = /** @lends OpenSeadragon.MouseTracker.prototype */{
 
         /**
          * Clean up any events or objects created by the mouse tracker.
@@ -243,8 +250,8 @@
          *      True if the original event is a touch event, otherwise false.
          * @param {Object} event.originalEvent
          *      The original event object.
-         * @param {Boolean} [event.preventDefaultAction=false]
+         * @param {Boolean} event.preventDefaultAction
-         *      Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent).
+         *      Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). Default: false.
          * @param {Object} event.userData
          *      Arbitrary user-defined object.
          */
@@ -268,8 +275,8 @@
          *      True if the original event is a touch event, otherwise false.
          * @param {Object} event.originalEvent
          *      The original event object.
-         * @param {Boolean} [event.preventDefaultAction=false]
+         * @param {Boolean} event.preventDefaultAction
-         *      Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent).
+         *      Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). Default: false.
          * @param {Object} event.userData
          *      Arbitrary user-defined object.
          */
@@ -288,8 +295,8 @@
          *      True if the original event is a touch event, otherwise false.
          * @param {Object} event.originalEvent
          *      The original event object.
-         * @param {Boolean} [event.preventDefaultAction=false]
+         * @param {Boolean} event.preventDefaultAction
-         *      Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent).
+         *      Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). Default: false.
          * @param {Object} event.userData
          *      Arbitrary user-defined object.
          */
@@ -313,8 +320,8 @@
          *      True if the original event is a touch event, otherwise false.
          * @param {Object} event.originalEvent
          *      The original event object.
-         * @param {Boolean} [event.preventDefaultAction=false]
+         * @param {Boolean} event.preventDefaultAction
-         *      Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent).
+         *      Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). Default: false.
          * @param {Object} event.userData
          *      Arbitrary user-defined object.
          */
@@ -333,8 +340,8 @@
          *      True if the original event is a touch event, otherwise false.
          * @param {Object} event.originalEvent
          *      The original event object.
-         * @param {Boolean} [event.preventDefaultAction=false]
+         * @param {Boolean} event.preventDefaultAction
-         *      Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent).
+         *      Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). Default: false.
          * @param {Object} event.userData
          *      Arbitrary user-defined object.
          */
@@ -357,8 +364,8 @@
          *      True if the original event is a touch event, otherwise false.
          * @param {Object} event.originalEvent
          *      The original event object.
-         * @param {Boolean} [event.preventDefaultAction=false]
+         * @param {Boolean} event.preventDefaultAction
-         *      Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent).
+         *      Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). Default: false.
          * @param {Object} event.userData
          *      Arbitrary user-defined object.
          */
@@ -374,15 +381,15 @@
          * @param {OpenSeadragon.Point} event.position
          *      The position of the event relative to the tracked element.
          * @param {Number} event.quick
-         *      True only if the clickDistThreshold and clickDeltaThreshold are both pased. Useful for ignoring events.
+         *      True only if the clickDistThreshold and clickDeltaThreshold are both passed. Useful for ignoring events.
          * @param {Boolean} event.shift
          *      True if the shift key was pressed during this event.
          * @param {Boolean} event.isTouchEvent
          *      True if the original event is a touch event, otherwise false.
          * @param {Object} event.originalEvent
          *      The original event object.
-         * @param {Boolean} [event.preventDefaultAction=false]
+         * @param {Boolean} event.preventDefaultAction
-         *      Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent).
+         *      Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). Default: false.
          * @param {Object} event.userData
          *      Arbitrary user-defined object.
          */
@@ -405,8 +412,8 @@
          *      True if the original event is a touch event, otherwise false.
          * @param {Object} event.originalEvent
          *      The original event object.
-         * @param {Boolean} [event.preventDefaultAction=false]
+         * @param {Boolean} event.preventDefaultAction
-         *      Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent).
+         *      Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). Default: false.
          * @param {Object} event.userData
          *      Arbitrary user-defined object.
          */
@@ -425,8 +432,8 @@
          *      True if the original event is a touch event, otherwise false.
          * @param {Object} event.originalEvent
          *      The original event object.
-         * @param {Boolean} [event.preventDefaultAction=false]
+         * @param {Boolean} event.preventDefaultAction
-         *      Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent).
+         *      Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). Default: false.
          * @param {Object} event.userData
          *      Arbitrary user-defined object.
          */
@@ -445,8 +452,8 @@
          *      True if the shift key was pressed during this event.
          * @param {Object} event.originalEvent
          *      The original event object.
-         * @param {Boolean} [event.preventDefaultAction=false]
+         * @param {Boolean} event.preventDefaultAction
-         *      Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent).
+         *      Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). Default: false.
          * @param {Object} event.userData
          *      Arbitrary user-defined object.
          */
@@ -461,8 +468,8 @@
          *      A reference to the tracker instance.
          * @param {Object} event.originalEvent
          *      The original event object.
-         * @param {Boolean} [event.preventDefaultAction=false]
+         * @param {Boolean} event.preventDefaultAction
-         *      Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent).
+         *      Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). Default: false.
          * @param {Object} event.userData
          *      Arbitrary user-defined object.
          */
@@ -477,8 +484,8 @@
          *      A reference to the tracker instance.
          * @param {Object} event.originalEvent
          *      The original event object.
-         * @param {Boolean} [event.preventDefaultAction=false]
+         * @param {Boolean} event.preventDefaultAction
-         *      Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent).
+         *      Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). Default: false.
          * @param {Object} event.userData
          *      Arbitrary user-defined object.
          */

src/navigator.js

@@ -35,17 +35,17 @@
 (function( $ ){
 
 /**
- * The Navigator provides a small view of the current image as fixed
+ * @class Navigator
+ * @classdesc The Navigator provides a small view of the current image as fixed
  * while representing the viewport as a moving box serving as a frame
  * of reference in the larger viewport as to which portion of the image
  * is currently being examined.  The navigator's viewport can be interacted
  * with using the keyboard or the mouse.
- * @class
+ *
- * @name OpenSeadragon.Navigator
+ * @memberof OpenSeadragon
  * @extends OpenSeadragon.Viewer
  * @extends OpenSeadragon.EventSource
  * @param {Object} options
- * @param {String} options.viewerId
  */
 $.Navigator = function( options ){
 
@@ -196,11 +196,10 @@ $.Navigator = function( options ){
 
 };
 
-$.extend( $.Navigator.prototype, $.EventSource.prototype, $.Viewer.prototype, {
+$.extend( $.Navigator.prototype, $.EventSource.prototype, $.Viewer.prototype, /** @lends OpenSeadragon.Navigator.prototype */{
 
     /**
      * @function
-     * @name OpenSeadragon.Navigator.prototype.update
      */
     update: function( viewport ){
 

src/openseadragon.js

@@ -82,45 +82,53 @@
  */
 
 
+/**
+ * @version  <%= pkg.name %> <%= pkg.version %>
+ *
+ * @file
+ * <h2><strong>OpenSeadragon - Javascript Deep Zooming</strong></h2>
+ * <p>
+ * OpenSeadragon provides an html interface for creating
+ * deep zoom user interfaces.  The simplest examples include deep
+ * zoom for large resolution images, and complex examples include
+ * zoomable map interfaces driven by SVG files.
+ * </p>
+ *
+ */
+
+/**
+ * @module OpenSeadragon
+ *
+ */
+
+/**
+ * The root namespace for OpenSeadragon.  All utility methods
+ * and classes are defined on or below this namespace.
+ *
+ * @namespace OpenSeadragon
+ *
+ */
+
+
+// Typedefs
 
  /**
-  * @version  <%= pkg.name %> <%= pkg.version %>
+  * All required and optional settings for instantiating a new instance of an OpenSeadragon image viewer.
   *
-  * @fileOverview
+  * @typedef {Object} Options
-  * <h2>
+  * @memberof OpenSeadragon
-  * <strong>
-  * OpenSeadragon - Javascript Deep Zooming
-  * </strong>
-  * </h2>
-  * <p>
-  * OpenSeadragon is provides an html interface for creating
-  * deep zoom user interfaces.  The simplest examples include deep
-  * zoom for large resolution images, and complex examples include
-  * zoomable map interfaces driven by SVG files.
-  * </p>
-  */
-
- /**
-  * The root namespace for OpenSeadragon, this function also serves as a single
-  * point of instantiation for an {@link OpenSeadragon.Viewer}, including all
-  * combinations of out-of-the-box configurable features.  All utility methods
-  * and classes are defined on or below this namespace.
   *
-  * @namespace
+  * @property {String} id
-  * @function
+  *     Id of the element to append the viewer's container element to. If not provided, the 'element' property must be provided.
-  * @name OpenSeadragon
+  *     If both the element and id properties are specified, the viewer is appended to the element provided in the element property.
-  * @exports $ as OpenSeadragon
   *
-  * @param {Object} options All required and optional settings for instantiating
+  * @property {Element} element
-  *     a new instance of an OpenSeadragon image viewer.
+  *     The element to append the viewer's container element to. If not provided, the 'id' property must be provided.
+  *     If both the element and id properties are specified, the viewer is appended to the element provided in the element property.
   *
-  * @param {String} options.xmlPath
+  * @property {Array|String|Function|Object[]|Array[]|String[]|Function[]} [tileSources=null]
-  *     DEPRECATED. A relative path to load a DZI file from the server.
+  *     As an Array, the tileSource can hold either Objects or mixed
-  *     Prefer the newer options.tileSources.
+  *     types of Arrays of Objects, Strings, or Functions. When a value is a String,
-  *
-  * @param {Array|String|Function|Object[]|Array[]|String[]|Function[]} options.tileSources
-  *     As an Array, the tileSource can hold either be all Objects or mixed
-  *     types of Arrays of Objects, String, Function. When a value is a String,
   *     the tileSource is used to create a {@link OpenSeadragon.DziTileSource}.
   *     When a value is a Function, the function is used to create a new
   *     {@link OpenSeadragon.TileSource} whose abstract method
@@ -128,147 +136,276 @@
   *     is an Array of objects, it is used to create a
   *     {@link OpenSeadragon.LegacyTileSource}.
   *
-  * @param {Boolean} [options.debugMode=true]
+  * @property {String} [xmlPath=null]
-  *     Currently does nothing. TODO: provide an in-screen panel providing event
+  *     <strong>DEPRECATED</strong>. A relative path to load a DZI file from the server.
-  *     detail feedback.
+  *     Prefer the newer Options.tileSources.
   *
-  * @param {Number} [options.animationTime=1.5]
+  * @property {String} [prefixUrl='/images/']
-  *     Specifies the animation duration per each {@link OpenSeadragon.Spring}
-  *     which occur when the image is dragged or zoomed.
-  *
-  * @param {Number} [options.blendTime=0.5]
-  *     Specifies the duration of animation as higher or lower level tiles are
-  *     replacing the existing tile.
-  *
-  * @param {Boolean} [options.alwaysBlend=false]
-  *     Forces the tile to always blend.  By default the tiles skip blending
-  *     when the blendTime is surpassed and the current animation frame would
-  *     not complete the blend.
-  *
-  * @param {Boolean} [options.autoHideControls=true]
-  *     If the user stops interacting with the viewport, fade the navigation
-  *     controls.  Useful for presentation since the controls are by default
-  *     floated on top of the image the user is viewing.
-  *
-  * @param {Boolean} [options.immediateRender=false]
-  *     Render the best closest level first, ignoring the lowering levels which
-  *     provide the effect of very blurry to sharp. It is recommended to change
-  *     setting to true for mobile devices.
-  *
-  * @param {Boolean} [options.wrapHorizontal=false]
-  *     Set to true to force the image to wrap horizontally within the viewport.
-  *     Useful for maps or images representing the surface of a sphere or cylinder.
-  *
-  * @param {Boolean} [options.wrapVertical=false]
-  *     Set to true to force the image to wrap vertically within the viewport.
-  *     Useful for maps or images representing the surface of a sphere or cylinder.
-  *
-  * @param {Number} [options.minZoomImageRatio=0.8]
-  *     The minimum percentage ( expressed as a number between 0 and 1 ) of
-  *     the viewport height or width at which the zoom out will be constrained.
-  *     Setting it to 0, for example will allow you to zoom out infinitly.
-  *
-  * @param {Number} [options.maxZoomPixelRatio=2]
-  *     The maximum ratio to allow a zoom-in to affect the highest level pixel
-  *     ratio. This can be set to Infinity to allow 'infinite' zooming into the
-  *     image though it is less effective visually if the HTML5 Canvas is not
-  *     availble on the viewing device.
-  *
-  * @param {Boolean} [options.autoResize=true]
-  *     Set to false to prevent polling for viewer size changes. Useful for providing custom resize behavior.
-  *
-  * @param {Number} [options.visibilityRatio=0.5]
-  *     The percentage ( as a number from 0 to 1 ) of the source image which
-  *     must be kept within the viewport.  If the image is dragged beyond that
-  *     limit, it will 'bounce' back until the minimum visibility ration is
-  *     achieved.  Setting this to 0 and wrapHorizontal ( or wrapVertical ) to
-  *     true will provide the effect of an infinitely scrolling viewport.
-  *
-  * @param {Number} [options.springStiffness=5.0]
-  *
-  * @param {Number} [options.imageLoaderLimit=0]
-  *     The maximum number of image requests to make concurrently.  By default
-  *     it is set to 0 allowing the browser to make the maximum number of
-  *     image requests in parallel as allowed by the browsers policy.
-  *
-  * @param {Number} [options.clickTimeThreshold=200]
-  *     If multiple mouse clicks occurs within less than this number of
-  *     milliseconds, treat them as a single click.
-  *
-  * @param {Number} [options.clickDistThreshold=5]
-  *     If a mouse or touch drag occurs and the distance to the starting drag
-  *     point is less than this many pixels, ignore the drag event.
-  *
-  * @param {Number} [options.zoomPerClick=2.0]
-  *     The "zoom distance" per mouse click or touch tap.
-  *
-  * @param {Number} [options.zoomPerScroll=1.2]
-  *     The "zoom distance" per mouse scroll or touch pinch.
-  *
-  * @param {Number} [options.zoomPerSecond=2.0]
-  *     The number of seconds to animate a single zoom event over.
-  *
-  * @param {Boolean} [options.showNavigationControl=true]
-  *     Set to false to prevent the appearance of the default navigation controls.
-  *
-  * @param {Boolean} [options.showNavigator=false]
-  *     Set to true to make the navigator minimap appear.
-  *
-  * @param {Boolean} [options.navigatorId=navigator-GENERATED DATE]
-  *     Set the ID of a div to hold the navigator minimap.  If one is not specified,
-  *     one will be generated and placed on top of the main image
-  *
-  * @param {Number} [options.controlsFadeDelay=2000]
-  *     The number of milliseconds to wait once the user has stopped interacting
-  *     with the interface before begining to fade the controls. Assumes
-  *     showNavigationControl and autoHideControls are both true.
-  *
-  * @param {Number} [options.controlsFadeLength=1500]
-  *     The number of milliseconds to animate the controls fading out.
-  *
-  * @param {Number} [options.maxImageCacheCount=100]
-  *     The max number of images we should keep in memory (per drawer).
-  *
-  * @param {Boolean} [options.useCanvas=true]
-  *     Set to false to not use an HTML canvas element for image rendering even if canvas is supported.
-  *
-  * @param {Number} [options.minPixelRatio=0.5]
-  *     The higher the minPixelRatio, the lower the quality of the image that
-  *     is considered sufficient to stop rendering a given zoom level.  For
-  *     example, if you are targeting mobile devices with less bandwith you may
-  *     try setting this to 1.5 or higher.
-  *
-  * @param {Boolean} [options.mouseNavEnabled=true]
-  *     Is the user able to interact with the image via mouse or touch. Default
-  *     interactions include draging the image in a plane, and zooming in toward
-  *     and away from the image.
-  *
-  * @param {Boolean} [options.preserveViewport=false]
-  *     If the viewer has been configured with a sequence of tile sources, then
-  *     normally navigating to through each image resets the viewport to 'home'
-  *     position.  If preserveViewport is set to true, then the viewport position
-  *     is preserved when navigating between images in the sequence.
-  *
-  * @param {String} [options.prefixUrl='/images/']
   *     Prepends the prefixUrl to navImages paths, which is very useful
   *     since the default paths are rarely useful for production
   *     environments.
   *
-  * @param {Object} [options.navImages=]
+  * @property {OpenSeadragon.NavImages} [navImages]
   *     An object with a property for each button or other built-in navigation
   *     control, eg the current 'zoomIn', 'zoomOut', 'home', and 'fullpage'.
-  *     Each of those in turn provides an image path for each state of the botton
+  *     Each of those in turn provides an image path for each state of the button
   *     or navigation control, eg 'REST', 'GROUP', 'HOVER', 'PRESS'. Finally the
   *     image paths, by default assume there is a folder on the servers root path
   *     called '/images', eg '/images/zoomin_rest.png'.  If you need to adjust
   *     these paths, prefer setting the option.prefixUrl rather than overriding
   *     every image path directly through this setting.
   *
-  * @param {Boolean} [options.navPrevNextWrap=false]
+  * @property {Object} [tileHost=null]
+  *     TODO: Implement this. Currently not used.
+  *
+  * @property {Boolean} [debugMode=false]
+  *     TODO: provide an in-screen panel providing event detail feedback.
+  *
+  * @property {String} [debugGridColor='#437AB2']
+  *
+  * @property {Number} [animationTime=1.2]
+  *     Specifies the animation duration per each {@link OpenSeadragon.Spring}
+  *     which occur when the image is dragged or zoomed.
+  *
+  * @property {Number} [blendTime=0]
+  *     Specifies the duration of animation as higher or lower level tiles are
+  *     replacing the existing tile.
+  *
+  * @property {Boolean} [alwaysBlend=false]
+  *     Forces the tile to always blend.  By default the tiles skip blending
+  *     when the blendTime is surpassed and the current animation frame would
+  *     not complete the blend.
+  *
+  * @property {Boolean} [autoHideControls=true]
+  *     If the user stops interacting with the viewport, fade the navigation
+  *     controls.  Useful for presentation since the controls are by default
+  *     floated on top of the image the user is viewing.
+  *
+  * @property {Boolean} [immediateRender=false]
+  *     Render the best closest level first, ignoring the lowering levels which
+  *     provide the effect of very blurry to sharp. It is recommended to change
+  *     setting to true for mobile devices.
+  *
+  * @property {Number} [defaultZoomLevel=0]
+  *     Zoom level to use when image is first opened or the home button is clicked.
+  *     If 0, adjusts to fit viewer.
+  *
+  * @property {Number} [degrees=0]
+  *     Initial rotation.
+  *
+  * @property {Number} [minZoomLevel=null]
+  *
+  * @property {Number} [maxZoomLevel=null]
+  *
+  * @property {Boolean} [panHorizontal=true]
+  *     Allow horizontal pan.
+  *
+  * @property {Boolean} [panVertical=true]
+  *     Allow vertical pan.
+  *
+  * @property {Boolean} [constrainDuringPan=false]
+  *
+  * @property {Boolean} [wrapHorizontal=false]
+  *     Set to true to force the image to wrap horizontally within the viewport.
+  *     Useful for maps or images representing the surface of a sphere or cylinder.
+  *
+  * @property {Boolean} [wrapVertical=false]
+  *     Set to true to force the image to wrap vertically within the viewport.
+  *     Useful for maps or images representing the surface of a sphere or cylinder.
+  *
+  * @property {Number} [minZoomImageRatio=0.9]
+  *     The minimum percentage ( expressed as a number between 0 and 1 ) of
+  *     the viewport height or width at which the zoom out will be constrained.
+  *     Setting it to 0, for example will allow you to zoom out infinitly.
+  *
+  * @property {Number} [maxZoomPixelRatio=1.1]
+  *     The maximum ratio to allow a zoom-in to affect the highest level pixel
+  *     ratio. This can be set to Infinity to allow 'infinite' zooming into the
+  *     image though it is less effective visually if the HTML5 Canvas is not
+  *     availble on the viewing device.
+  *
+  * @property {Boolean} [autoResize=true]
+  *     Set to false to prevent polling for viewer size changes. Useful for providing custom resize behavior.
+  *
+  * @property {Number} [pixelsPerWheelLine=40]
+  *     For pixel-resolution scrolling devices, the number of pixels equal to one scroll line.
+  *
+  * @property {Number} [visibilityRatio=0.5]
+  *     The percentage ( as a number from 0 to 1 ) of the source image which
+  *     must be kept within the viewport.  If the image is dragged beyond that
+  *     limit, it will 'bounce' back until the minimum visibility ration is
+  *     achieved.  Setting this to 0 and wrapHorizontal ( or wrapVertical ) to
+  *     true will provide the effect of an infinitely scrolling viewport.
+  *
+  * @property {Number} [springStiffness=7.0]
+  *
+  * @property {Number} [imageLoaderLimit=0]
+  *     The maximum number of image requests to make concurrently.  By default
+  *     it is set to 0 allowing the browser to make the maximum number of
+  *     image requests in parallel as allowed by the browsers policy.
+  *
+  * @property {Number} [clickTimeThreshold=300]
+  *     If multiple mouse clicks occurs within less than this number of
+  *     milliseconds, treat them as a single click.
+  *
+  * @property {Number} [clickDistThreshold=5]
+  *     If a mouse or touch drag occurs and the distance to the starting drag
+  *     point is less than this many pixels, ignore the drag event.
+  *
+  * @property {Number} [zoomPerClick=2.0]
+  *     The "zoom distance" per mouse click or touch tap. <em><strong>Note:</strong> Setting this to 1.0 effectively disables the click-to-zoom feature.</em>
+  *
+  * @property {Number} [zoomPerScroll=1.2]
+  *     The "zoom distance" per mouse scroll or touch pinch. <em><strong>Note:</strong> Setting this to 1.0 effectively disables the mouse-wheel zoom feature.</em>
+  *
+  * @property {Number} [zoomPerSecond=1.0]
+  *     The number of seconds to animate a single zoom event over.
+  *
+  * @property {Boolean} [showNavigationControl=true]
+  *     Set to false to prevent the appearance of the default navigation controls.
+  *
+  * @property {Boolean} [showNavigator=false]
+  *     Set to true to make the navigator minimap appear.
+  *
+  * @property {Boolean} [navigatorId=navigator-GENERATED DATE]
+  *     Set the ID of a div to hold the navigator minimap.  If one is not specified,
+  *     one will be generated and placed on top of the main image
+  *
+  * @property {Number} [navigatorHeight=null]
+  *     TODO: Implement this. Currently not used.
+  *
+  * @property {Number} [navigatorWidth=null]
+  *     TODO: Implement this. Currently not used.
+  *
+  * @property {Number} [navigatorPosition=null]
+  *     TODO: Implement this. Currently not used.
+  *
+  * @property {Number} [navigatorSizeRatio=0.2]
+  *     Ratio of navigator size to viewer size.
+  *
+  * @property {Number} [controlsFadeDelay=2000]
+  *     The number of milliseconds to wait once the user has stopped interacting
+  *     with the interface before begining to fade the controls. Assumes
+  *     showNavigationControl and autoHideControls are both true.
+  *
+  * @property {Number} [controlsFadeLength=1500]
+  *     The number of milliseconds to animate the controls fading out.
+  *
+  * @property {Number} [maxImageCacheCount=200]
+  *     The max number of images we should keep in memory (per drawer).
+  *
+  * @property {Number} [timeout=30000]
+  *
+  * @property {Boolean} [useCanvas=true]
+  *     Set to false to not use an HTML canvas element for image rendering even if canvas is supported.
+  *
+  * @property {Number} [minPixelRatio=0.5]
+  *     The higher the minPixelRatio, the lower the quality of the image that
+  *     is considered sufficient to stop rendering a given zoom level.  For
+  *     example, if you are targeting mobile devices with less bandwith you may
+  *     try setting this to 1.5 or higher.
+  *
+  * @property {Boolean} [mouseNavEnabled=true]
+  *     Is the user able to interact with the image via mouse or touch. Default
+  *     interactions include draging the image in a plane, and zooming in toward
+  *     and away from the image.
+  *
+  * @property {Boolean} [navPrevNextWrap=false]
   *     If the 'previous' button will wrap to the last image when viewing the first
   *     image and if the 'next' button will wrap to the first image when viewing
   *     the last image.
   *
+  * @property {Boolean} [showSequenceControl=true]
+  *     If the viewer has been configured with a sequence of tile sources, then
+  *     provide buttons for navigating forward and backward through the images.
+  *
+  * @property {Number} [initialPage=0]
+  *     If the viewer has been configured with a sequence of tile sources, display this page initially.
+  *
+  * @property {Boolean} [preserveViewport=false]
+  *     If the viewer has been configured with a sequence of tile sources, then
+  *     normally navigating to through each image resets the viewport to 'home'
+  *     position.  If preserveViewport is set to true, then the viewport position
+  *     is preserved when navigating between images in the sequence.
+  *
+  * @property {Boolean} [showReferenceStrip=false]
+  *     If the viewer has been configured with a sequence of tile sources, then
+  *     display a scrolling strip of image thumbnails for navigating through the images.
+  *
+  * @property {String} [referenceStripScroll='horizontal']
+  *
+  * @property {Element} [referenceStripElement=null]
+  *
+  * @property {Number} [referenceStripHeight=null]
+  *
+  * @property {Number} [referenceStripWidth=null]
+  *
+  * @property {String} [referenceStripPosition='BOTTOM_LEFT']
+  *
+  * @property {Number} [referenceStripSizeRatio=0.2]
+  *
+  * @property {Boolean} [collectionMode=false]
+  *
+  * @property {Number} [collectionRows=3]
+  *
+  * @property {String} [collectionLayout='horizontal']
+  *
+  * @property {Number} [collectionTileSize=800]
+  *
+  */
+
+/**
+  * The names for the image resources used for the image navigation buttons.
+  *
+  * @typedef {Object} NavImages
+  * @memberof OpenSeadragon
+  *
+  * @property {Object} zoomIn - Images for the zoom-in button.
+  * @property {String} zoomIn.REST
+  * @property {String} zoomIn.GROUP
+  * @property {String} zoomIn.HOVER
+  * @property {String} zoomIn.DOWN
+  *
+  * @property {Object} zoomOut - Images for the zoom-out button.
+  * @property {String} zoomOut.REST
+  * @property {String} zoomOut.GROUP
+  * @property {String} zoomOut.HOVER
+  * @property {String} zoomOut.DOWN
+  *
+  * @property {Object} home - Images for the home button.
+  * @property {String} home.REST
+  * @property {String} home.GROUP
+  * @property {String} home.HOVER
+  * @property {String} home.DOWN
+  *
+  * @property {Object} fullpage - Images for the full-page button.
+  * @property {String} fullpage.REST
+  * @property {String} fullpage.GROUP
+  * @property {String} fullpage.HOVER
+  * @property {String} fullpage.DOWN
+  *
+  * @property {Object} previous - Images for the previous button.
+  * @property {String} previous.REST
+  * @property {String} previous.GROUP
+  * @property {String} previous.HOVER
+  * @property {String} previous.DOWN
+  *
+  * @property {Object} next - Images for the next button.
+  * @property {String} next.REST
+  * @property {String} next.GROUP
+  * @property {String} next.HOVER
+  * @property {String} next.DOWN
+  *
+  */
+
+
+ /**
+  * This function serves as a single point of instantiation for an {@link OpenSeadragon.Viewer}, including all
+  * combinations of out-of-the-box configurable features.
+  *
+  * @function OpenSeadragon
+  * @memberof module:OpenSeadragon
+  * @param {OpenSeadragon.Options} options - Viewer options.
   * @returns {OpenSeadragon.Viewer}
   */
 window.OpenSeadragon = window.OpenSeadragon || function( options ){
@@ -277,33 +414,54 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
 
 };
 
+
 (function( $ ){
 
 
+    /**
+     * The OpenSeadragon version.
+     *
+     * @member {Object} OpenSeadragon.version
+     * @property {String} versionStr - The version number as a string ('major.minor.revision').
+     * @property {Number} major - The major version number.
+     * @property {Number} minor - The minor version number.
+     * @property {Number} revision - The revision number.
+     * @since 1.0.0
+     */
+    /* jshint ignore:start */
+    $.version = {
+        versionStr: '<%= osdVersion.versionStr %>',
+        major: <%= osdVersion.major %>,
+        minor: <%= osdVersion.minor %>,
+        revision: <%= osdVersion.revision %>
+    };
+    /* jshint ignore:end */
+
+
     /**
      * Taken from jquery 1.6.1
      * [[Class]] -> type pairs
      * @private
      */
     var class2type = {
-        '[object Boolean]':     'boolean',
+            '[object Boolean]':     'boolean',
-        '[object Number]':      'number',
+            '[object Number]':      'number',
-        '[object String]':      'string',
+            '[object String]':      'string',
-        '[object Function]':    'function',
+            '[object Function]':    'function',
-        '[object Array]':       'array',
+            '[object Array]':       'array',
-        '[object Date]':        'date',
+            '[object Date]':        'date',
-        '[object RegExp]':      'regexp',
+            '[object RegExp]':      'regexp',
-        '[object Object]':      'object'
+            '[object Object]':      'object'
-    },
+        },
-    // Save a reference to some core methods
+        // Save a reference to some core methods
-    toString    = Object.prototype.toString,
+        toString    = Object.prototype.toString,
-    hasOwn      = Object.prototype.hasOwnProperty;
+        hasOwn      = Object.prototype.hasOwnProperty;
 
     /**
      * Taken from jQuery 1.6.1
-     * @name $.isFunction
+     * @function isFunction
-     * @function
+     * @memberof OpenSeadragon
-     * @see <a href='http://www.jquery.com/'>jQuery</a>
+     * @see {@link http://www.jquery.com/ jQuery}
      */
     $.isFunction = function( obj ) {
         return $.type(obj) === "function";
@@ -312,9 +470,9 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
 
     /**
      * Taken from jQuery 1.6.1
-     * @name $.isArray
+     * @function isArray
-     * @function
+     * @memberof OpenSeadragon
-     * @see <a href='http://www.jquery.com/'>jQuery</a>
+     * @see {@link http://www.jquery.com/ jQuery}
      */
     $.isArray = Array.isArray || function( obj ) {
         return $.type(obj) === "array";
@@ -324,9 +482,9 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
     /**
      * A crude way of determining if an object is a window.
      * Taken from jQuery 1.6.1
-     * @name $.isWindow
+     * @function isWindow
-     * @function
+     * @memberof OpenSeadragon
-     * @see <a href='http://www.jquery.com/'>jQuery</a>
+     * @see {@link http://www.jquery.com/ jQuery}
      */
     $.isWindow = function( obj ) {
         return obj && typeof obj === "object" && "setInterval" in obj;
@@ -335,9 +493,9 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
 
     /**
      * Taken from jQuery 1.6.1
-     * @name $.type
+     * @function type
-     * @function
+     * @memberof OpenSeadragon
-     * @see <a href='http://www.jquery.com/'>jQuery</a>
+     * @see {@link http://www.jquery.com/ jQuery}
      */
     $.type = function( obj ) {
         return ( obj === null ) || ( obj === undefined ) ?
@@ -348,9 +506,9 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
 
     /**
      * Taken from jQuery 1.6.1
-     * @name $.isPlainObject
+     * @function isPlainObject
-     * @function
+     * @memberof OpenSeadragon
-     * @see <a href='http://www.jquery.com/'>jQuery</a>
+     * @see {@link http://www.jquery.com/ jQuery}
      */
     $.isPlainObject = function( obj ) {
         // Must be an Object.
@@ -379,9 +537,9 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
 
     /**
      * Taken from jQuery 1.6.1
-     * @name $.isEmptyObject
+     * @function isEmptyObject
-     * @function
+     * @memberof OpenSeadragon
-     * @see <a href='http://www.jquery.com/'>jQuery</a>
+     * @see {@link http://www.jquery.com/ jQuery}
      */
     $.isEmptyObject = function( obj ) {
         for ( var name in obj ) {
@@ -393,8 +551,8 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
 
     /**
      * True if the browser supports the HTML5 canvas element
-     * @name $.supportsCanvas
+     * @member {Boolean} supportsCanvas
-     * @property
+     * @memberof OpenSeadragon
      */
     $.supportsCanvas = (function () {
         var canvasElement = document.createElement( 'canvas' );
@@ -421,7 +579,9 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
 
     /**
      * Taken from jQuery 1.6.1
-     * @see <a href='http://www.jquery.com/'>jQuery</a>
+     * @function extend
+     * @memberof OpenSeadragon
+     * @see {@link http://www.jquery.com/ jQuery}
      */
     $.extend = function() {
         var options,
@@ -494,12 +654,11 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
     };
 
 
-    $.extend( $, {
+    $.extend( $, /** @lends OpenSeadragon */{
         /**
-         * These are the default values for the optional settings documented
+         * The default values for the optional settings documented at {@link OpenSeadragon.Options}.
-         * in the {@link OpenSeadragon} constructor detail.
-         * @name $.DEFAULT_SETTINGS
          * @static
+         * @type {Object}
          */
         DEFAULT_SETTINGS: {
             //DATA SOURCE DETAILS
@@ -635,11 +794,11 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
 
 
         /**
-         * Invokes the the method as if it where a method belonging to the object.
+         * Returns a function which invokes the method as if it were a method belonging to the object.
-         * @name $.delegate
          * @function
          * @param {Object} object
          * @param {Function} method
+         * @returns {Function}
          */
         delegate: function( object, method ) {
             return function(){
@@ -653,10 +812,15 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
 
 
         /**
-         * An enumeration of Browser vendors including UNKNOWN, IE, FIREFOX,
+         * An enumeration of Browser vendors.
-         * SAFARI, CHROME, and OPERA.
-         * @name $.BROWSERS
          * @static
+         * @type {Object}
+         * @property {Number} UNKNOWN
+         * @property {Number} IE
+         * @property {Number} FIREFOX
+         * @property {Number} SAFARI
+         * @property {Number} CHROME
+         * @property {Number} OPERA
          */
         BROWSERS: {
             UNKNOWN:    0,
@@ -671,7 +835,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
         /**
          * Returns a DOM Element for the given id or element.
          * @function
-         * @name OpenSeadragon.getElement
          * @param {String|Element} element Accepts an id or element.
          * @returns {Element} The element with the given id, null, or the element itself.
          */
@@ -686,9 +849,8 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
         /**
          * Determines the position of the upper-left corner of the element.
          * @function
-         * @name OpenSeadragon.getElementPosition
          * @param {Element|String} element - the elemenet we want the position for.
-         * @returns {Point} - the position of the upper left corner of the element.
+         * @returns {OpenSeadragon.Point} - the position of the upper left corner of the element.
          */
         getElementPosition: function( element ) {
             var result = new $.Point(),
@@ -720,9 +882,8 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
         /**
          * Determines the position of the upper-left corner of the element adjusted for current page and/or element scroll.
          * @function
-         * @name OpenSeadragon.getElementOffset
          * @param {Element|String} element - the element we want the position for.
-         * @returns {Point} - the position of the upper left corner of the element adjusted for current page and/or element scroll.
+         * @returns {OpenSeadragon.Point} - the position of the upper left corner of the element adjusted for current page and/or element scroll.
          */
         getElementOffset: function( element ) {
             element = $.getElement( element );
@@ -758,9 +919,8 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
         /**
          * Determines the height and width of the given element.
          * @function
-         * @name OpenSeadragon.getElementSize
          * @param {Element|String} element
-         * @returns {Point}
+         * @returns {OpenSeadragon.Point}
          */
         getElementSize: function( element ) {
             element = $.getElement( element );
@@ -775,7 +935,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
         /**
          * Returns the CSSStyle object for the given element.
          * @function
-         * @name OpenSeadragon.getElementStyle
          * @param {Element|String} element
          * @returns {CSSStyle}
          */
@@ -793,12 +952,12 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
 
         /**
          * Gets the latest event, really only useful internally since its
-         * specific to IE behavior.  TODO: Deprecate this from the api and
+         * specific to IE behavior.
-         * use it internally.
          * @function
-         * @name OpenSeadragon.getEvent
          * @param {Event} [event]
          * @returns {Event}
+         * @deprecated For internal use only
+         * @private
          */
         getEvent: function( event ) {
             if( event ){
@@ -817,9 +976,8 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
         /**
          * Gets the position of the mouse on the screen for a given event.
          * @function
-         * @name OpenSeadragon.getMousePosition
          * @param {Event} [event]
-         * @returns {Point}
+         * @returns {OpenSeadragon.Point}
          */
         getMousePosition: function( event ) {
 
@@ -862,8 +1020,7 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
         /**
          * Determines the page's current scroll position.
          * @function
-         * @name OpenSeadragon.getPageScroll
+         * @returns {OpenSeadragon.Point}
-         * @returns {Point}
          */
         getPageScroll: function() {
             var docElement  = document.documentElement || {},
@@ -901,8 +1058,7 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
         /**
          * Set the page scroll position.
          * @function
-         * @name OpenSeadragon.getPageScroll
+         * @returns {OpenSeadragon.Point}
-         * @returns {Point}
          */
         setPageScroll: function( scroll ) {
             if ( typeof ( window.scrollTo ) !== "undefined" ) {
@@ -953,8 +1109,7 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
         /**
          * Determines the size of the browsers window.
          * @function
-         * @name OpenSeadragon.getWindowSize
+         * @returns {OpenSeadragon.Point}
-         * @returns {Point}
          */
         getWindowSize: function() {
             var docElement = document.documentElement || {},
@@ -993,7 +1148,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
          * Wraps the given element in a nest of divs so that the element can
          * be easily centered using CSS tables
          * @function
-         * @name OpenSeadragon.makeCenteredNode
          * @param {Element|String} element
          * @returns {Element} outermost wrapper element
          */
@@ -1041,7 +1195,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
          * Creates an easily positionable element of the given type that therefor
          * serves as an excellent container element.
          * @function
-         * @name OpenSeadragon.makeNeutralElement
          * @param {String} tagName
          * @returns {Element}
          */
@@ -1061,7 +1214,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
 
         /**
          * Returns the current milliseconds, using Date.now() if available
-         * @name $.now
          * @function
          */
         now: function( ) {
@@ -1080,7 +1232,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
          * Generally only IE has issues doing this correctly for formats like
          * png.
          * @function
-         * @name OpenSeadragon.makeTransparentImage
          * @param {String} src
          * @returns {Element}
          */
@@ -1129,7 +1280,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
         /**
          * Sets the opacity of the specified element.
          * @function
-         * @name OpenSeadragon.setElementOpacity
          * @param {Element|String} element
          * @param {Number} opacity
          * @param {Boolean} [usesAlpha]
@@ -1161,7 +1311,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
 
         /**
          * Add the specified CSS class to the element if not present.
-         * @name $.addClass
          * @function
          * @param {Element|String} element
          * @param {String} className
@@ -1180,7 +1329,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
 
         /**
          * Remove the specified CSS class from the element.
-         * @name $.removeClass
          * @function
          * @param {Element|String} element
          * @param {String} className
@@ -1204,7 +1352,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
         /**
          * Adds an event listener for the given element, eventName and handler.
          * @function
-         * @name OpenSeadragon.addEvent
          * @param {Element|String} element
          * @param {String} eventName
          * @param {Function} handler
@@ -1234,7 +1381,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
          * Remove a given event listener for the given element, event type and
          * handler.
          * @function
-         * @name OpenSeadragon.removeEvent
          * @param {Element|String} element
          * @param {String} eventName
          * @param {Function} handler
@@ -1264,7 +1410,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
          * Cancels the default browser behavior had the event propagated all
          * the way up the DOM to the window object.
          * @function
-         * @name OpenSeadragon.cancelEvent
          * @param {Event} [event]
          */
         cancelEvent: function( event ) {
@@ -1291,7 +1436,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
         /**
          * Stops the propagation of the event up the DOM.
          * @function
-         * @name OpenSeadragon.stopEvent
          * @param {Event} [event]
          */
         stopEvent: function( event ) {
@@ -1323,7 +1467,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
          * invocation, and each invocation can add additional arguments as well.
          *
          * @function
-         * @name OpenSeadragon.createCallback
          * @param {Object} object
          * @param {Function} method
          * @param [args] any additional arguments are passed as arguments to the
@@ -1355,7 +1498,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
         /**
          * Retreives the value of a url parameter from the window.location string.
          * @function
-         * @name OpenSeadragon.getUrlParameter
          * @param {String} key
          * @returns {String} The value of the url parameter or null if no param matches.
          */
@@ -1400,7 +1542,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
         /**
          * Makes an AJAX request.
          * @function
-         * @name OpenSeadragon.makeAjaxRequest
          * @param {String} url - the url to request
          * @param {Function} onSuccess - a function to call on a successful response
          * @param {Function} onError - a function to call on when an error occurs
@@ -1465,7 +1606,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
         /**
          * Taken from jQuery 1.6.1
          * @function
-         * @name OpenSeadragon.jsonp
          * @param {Object} options
          * @param {String} options.url
          * @param {Function} options.callback
@@ -1546,8 +1686,7 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
         /**
          * Fully deprecated. Will throw an error.
          * @function
-         * @name OpenSeadragon.createFromDZI
+         * @deprecated use {@link OpenSeadragon.Viewer#open}
-         * @deprecated - use OpenSeadragon.Viewer.prototype.open
          */
         createFromDZI: function() {
             throw "OpenSeadragon.createFromDZI is deprecated, use Viewer.open.";
@@ -1556,7 +1695,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
         /**
          * Parses an XML string into a DOM Document.
          * @function
-         * @name OpenSeadragon.parseXml
          * @param {String} string
          * @returns {Document}
          */
@@ -1598,7 +1736,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
          * Reports whether the image format is supported for tiling in this
          * version.
          * @function
-         * @name OpenSeadragon.imageFormatSupported
          * @param {String} [extension]
          * @returns {Boolean}
          */
@@ -1611,12 +1748,14 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
 
 
     /**
-     * The current browser vendor, version, and related information regarding
+     * The current browser vendor, version, and related information regarding detected features.
-     * detected features.  Features include <br/>
+     * @member {Object} Browser
-     *  <strong>'alpha'</strong> - Does the browser support image alpha
+     * @memberof OpenSeadragon
-     *  transparency.<br/>
-     * @name $.Browser
      * @static
+     * @type {Object}
+     * @property {OpenSeadragon.BROWSERS} vendor - One of the {@link OpenSeadragon.BROWSERS} enumeration values.
+     * @property {Number} version
+     * @property {Boolean} alpha - Does the browser support image alpha transparency.
      */
     $.Browser = {
         vendor:     $.BROWSERS.UNKNOWN,

src/osmtilesource.js

@@ -43,12 +43,13 @@
 (function( $ ){
 
 /**
- * A tilesource implementation for OpenStreetMap.
+ * @class OsmTileSource
+ * @classdesc A tilesource implementation for OpenStreetMap.<br><br>
  *
  * Note 1. Zoomlevels. Deep Zoom and OSM define zoom levels differently. In  Deep
  * Zoom, level 0 equals an image of 1x1 pixels. In OSM, level 0 equals an image of
  * 256x256 levels (see http://gasi.ch/blog/inside-deep-zoom-2). I.e. there is a
- * difference of log2(256)=8 levels.
+ * difference of log2(256)=8 levels.<br><br>
  *
  * Note 2. Image dimension. According to the OSM Wiki
  * (http://wiki.openstreetmap.org/wiki/Slippy_map_tilenames#Zoom_levels)
@@ -56,7 +57,7 @@
  * pixel size. I.e. the Deep Zoom image dimension is 65.572.864x65.572.864
  * pixels.
  *
- * @class
+ * @memberof OpenSeadragon
  * @extends OpenSeadragon.TileSource
  * @param {Number|Object} width - the pixel width of the image or the idiomatic
  *      options object which is used instead of positional arguments.
@@ -99,14 +100,13 @@ $.OsmTileSource = function( width, height, tileSize, tileOverlap, tilesUrl ) {
 
 };
 
-$.extend( $.OsmTileSource.prototype, $.TileSource.prototype, {
+$.extend( $.OsmTileSource.prototype, $.TileSource.prototype, /** @lends OpenSeadragon.OsmTileSource.prototype */{
 
 
     /**
      * Determine if the data and/or url imply the image service is supported by
      * this tile source.
      * @function
-     * @name OpenSeadragon.OsmTileSource.prototype.supports
      * @param {Object|Array} data
      * @param {String} optional - url
      */
@@ -120,7 +120,6 @@ $.extend( $.OsmTileSource.prototype, $.TileSource.prototype, {
     /**
      *
      * @function
-     * @name OpenSeadragon.OsmTileSource.prototype.configure
      * @param {Object} data - the raw configuration
      * @param {String} url - the url the data was retreived from if any.
      * @return {Object} options - A dictionary of keyword arguments sufficient
@@ -133,7 +132,6 @@ $.extend( $.OsmTileSource.prototype, $.TileSource.prototype, {
 
     /**
      * @function
-     * @name OpenSeadragon.OsmTileSource.prototype.getTileUrl
      * @param {Number} level
      * @param {Number} x
      * @param {Number} y

src/overlay.js

@@ -35,10 +35,20 @@
 (function( $ ){
 
     /**
-     * An enumeration of positions that an overlay may be assigned relative
+     * An enumeration of positions that an overlay may be assigned relative to the viewport.
-     * to the viewport including CENTER, TOP_LEFT (default), TOP, TOP_RIGHT,
+     * @member OverlayPlacement
-     * RIGHT, BOTTOM_RIGHT, BOTTOM, BOTTOM_LEFT, and LEFT.
+     * @memberof OpenSeadragon
      * @static
+     * @type {Object}
+     * @property {Number} CENTER
+     * @property {Number} TOP_LEFT
+     * @property {Number} TOP
+     * @property {Number} TOP_RIGHT
+     * @property {Number} RIGHT
+     * @property {Number} BOTTOM_RIGHT
+     * @property {Number} BOTTOM
+     * @property {Number} BOTTOM_LEFT
+     * @property {Number} LEFT
      */
     $.OverlayPlacement = {
         CENTER:       0,
@@ -53,11 +63,28 @@
     };
 
     /**
-     * An Overlay provides a
+     * @class Overlay
-     * @class
+     * @classdesc Provides a way to float an HTML element on top of the viewer element.
+     *
+     * @memberof OpenSeadragon
+     * @param {Object} options
+     * @param {Element} options.element
+     * @param {OpenSeadragon.Point|OpenSeadragon.Rect} options.location
+     * @param {OpenSeadragon.OverlayPlacement} options.placement - Only used if location is an {@link OpenSeadragon.Point}.
+     * @param {OpenSeadragon.Overlay.OnDrawCallback} options.onDraw
      */
     $.Overlay = function( element, location, placement ) {
 
+        /**
+         * onDraw callback signature used by {@link OpenSeadragon.Overlay}.
+         *
+         * @callback OnDrawCallback
+         * @memberof OpenSeadragon.Overlay
+         * @param {OpenSeadragon.Point} position
+         * @param {OpenSeadragon.Point} size
+         * @param {Element} element
+         */
+
         var options;
         if( $.isPlainObject( element ) ){
             options = element;
@@ -93,7 +120,7 @@
         this.onDraw = options.onDraw;
     };
 
-    $.Overlay.prototype = {
+    $.Overlay.prototype = /** @lends OpenSeadragon.Overlay.prototype */{
 
         /**
          * @function

src/point.js

@@ -35,21 +35,31 @@
 (function( $ ){
 
 /**
- * A Point is really used as a 2-dimensional vector, equally useful for
+ * @class Point
+ * @classdesc A Point is really used as a 2-dimensional vector, equally useful for
  * representing a point on a plane, or the height and width of a plane
  * not requiring any other frame of reference.
- * @class
+ *
+ * @memberof OpenSeadragon
  * @param {Number} [x] The vector component 'x'. Defaults to the origin at 0.
  * @param {Number} [y] The vector component 'y'. Defaults to the origin at 0.
- * @property {Number} [x] The vector component 'x'.
- * @property {Number} [y] The vector component 'y'.
  */
 $.Point = function( x, y ) {
+    /**
+     * The vector component 'x'.
+     * @member {Number} x
+     * @memberof OpenSeadragon.Point#
+     */
     this.x = typeof ( x ) == "number" ? x : 0;
+    /**
+     * The vector component 'y'.
+     * @member {Number} y
+     * @memberof OpenSeadragon.Point#
+     */
     this.y = typeof ( y ) == "number" ? y : 0;
 };
 
-$.Point.prototype = {
+$.Point.prototype = /** @lends OpenSeadragon.Point.prototype */{
 
     /**
      * Add another Point to this point and return a new Point.

src/profiler.js

@@ -35,9 +35,11 @@
 (function( $ ){
 
 /**
- * A utility class useful for developers to establish baseline performance
+ * @class Profiler
+ * @classdesc A utility class useful for developers to establish baseline performance
  * metrics of rendering routines.
- * @class
+ *
+ * @memberof OpenSeadragon
  * @property {Boolean} midUpdate
  * @property {Number} numUpdates
  * @property {Number} lastBeginTime
@@ -66,7 +68,7 @@ $.Profiler = function() {
     this.maxIdleTime = 0;
 };
 
-$.Profiler.prototype = {
+$.Profiler.prototype = /** @lends OpenSeadragon.Profiler.prototype */{
 
     /**
      * @function

src/rectangle.js

@@ -35,29 +35,46 @@
 (function( $ ){
 
 /**
- * A Rectangle really represents a 2x2 matrix where each row represents a
+ * @class Rect
+ * @classdesc A Rectangle really represents a 2x2 matrix where each row represents a
  * 2 dimensional vector component, the first is (x,y) and the second is
  * (width, height).  The latter component implies the equation of a simple
  * plane.
  *
- * @class
+ * @memberof OpenSeadragon
  * @param {Number} x The vector component 'x'.
  * @param {Number} y The vector component 'y'.
  * @param {Number} width The vector component 'height'.
  * @param {Number} height The vector component 'width'.
- * @property {Number} x The vector component 'x'.
- * @property {Number} y The vector component 'y'.
- * @property {Number} width The vector component 'width'.
- * @property {Number} height The vector component 'height'.
  */
 $.Rect = function( x, y, width, height ) {
+    /**
+     * The vector component 'x'.
+     * @member {Number} x
+     * @memberof OpenSeadragon.Rect#
+     */
     this.x = typeof ( x ) == "number" ? x : 0;
+    /**
+     * The vector component 'y'.
+     * @member {Number} y
+     * @memberof OpenSeadragon.Rect#
+     */
     this.y = typeof ( y ) == "number" ? y : 0;
+    /**
+     * The vector component 'width'.
+     * @member {Number} width
+     * @memberof OpenSeadragon.Rect#
+     */
     this.width  = typeof ( width )  == "number" ? width : 0;
+    /**
+     * The vector component 'height'.
+     * @member {Number} height
+     * @memberof OpenSeadragon.Rect#
+     */
     this.height = typeof ( height ) == "number" ? height : 0;
 };
 
-$.Rect.prototype = {
+$.Rect.prototype = /** @lends OpenSeadragon.Rect.prototype */{
 
     /**
      * The aspect ratio is simply the ratio of width to height.

src/referencestrip.js

@@ -56,6 +56,11 @@ var THIS = {};
  *          require better abstraction at those points in order to effeciently
  *          reuse those paradigms.
  */
+/**
+ * @class ReferenceStrip
+ * @memberof OpenSeadragon
+ * @param {Object} options
+ */
 $.ReferenceStrip = function ( options ) {
 
     var _this       = this,
@@ -220,8 +225,11 @@ $.ReferenceStrip = function ( options ) {
 
 };
 
-$.extend( $.ReferenceStrip.prototype, $.EventSource.prototype, $.Viewer.prototype, {
+$.extend( $.ReferenceStrip.prototype, $.EventSource.prototype, $.Viewer.prototype, /** @lends OpenSeadragon.ReferenceStrip.prototype */{
 
+    /**
+     * @function
+     */
     setFocus: function ( page ) {
         var element      = $.getElement( this.element.id + '-' + page ),
             viewerSize   = $.getElementSize( this.viewer.canvas ),
@@ -268,9 +276,9 @@ $.extend( $.ReferenceStrip.prototype, $.EventSource.prototype, $.Viewer.prototyp
             onStripEnter.call( this, { eventSource: this.innerTracker } );
         }
     },
+
     /**
      * @function
-     * @name OpenSeadragon.ReferenceStrip.prototype.update
      */
     update: function () {
         if ( THIS[this.id].animating ) {

src/spring.js

@@ -35,20 +35,13 @@
 (function( $ ){
 
 /**
- * @class
+ * @class Spring
+ * @memberof OpenSeadragon
  * @param {Object} options - Spring configuration settings.
  * @param {Number} options.initial - Initial value of spring, default to 0 so
  *  spring is not in motion initally by default.
  * @param {Number} options.springStiffness - Spring stiffness.
  * @param {Number} options.animationTime - Animation duration per spring.
- *
- * @property {Number} initial - Initial value of spring, default to 0 so
- *  spring is not in motion initally by default.
- * @property {Number} springStiffness - Spring stiffness.
- * @property {Number} animationTime - Animation duration per spring.
- * @property {Object} current
- * @property {Number} start
- * @property {Number} target
  */
 $.Spring = function( options ) {
     var args = arguments;
@@ -60,9 +53,19 @@ $.Spring = function( options ) {
             initial: args.length && typeof ( args[ 0 ] ) == "number" ?
                 args[ 0 ] :
                 0,
+            /**
+             * Spring stiffness.
+             * @member {Number} springStiffness
+             * @memberof OpenSeadragon.Spring#
+             */
             springStiffness: args.length > 1 ?
                 args[ 1 ].springStiffness :
                 5.0,
+            /**
+             * Animation duration per spring.
+             * @member {Number} animationTime
+             * @memberof OpenSeadragon.Spring#
+             */
             animationTime: args.length > 1 ?
                 args[ 1 ].animationTime :
                 1.5
@@ -71,7 +74,12 @@ $.Spring = function( options ) {
 
     $.extend( true, this, options);
 
-
+    /**
+     * @member {Object} current
+     * @memberof OpenSeadragon.Spring#
+     * @property {Number} value
+     * @property {Number} time
+     */
     this.current = {
         value: typeof ( this.initial ) == "number" ?
             this.initial :
@@ -79,18 +87,30 @@ $.Spring = function( options ) {
         time:  $.now() // always work in milliseconds
     };
 
+    /**
+     * @member {Object} start
+     * @memberof OpenSeadragon.Spring#
+     * @property {Number} value
+     * @property {Number} time
+     */
     this.start = {
         value: this.current.value,
         time:  this.current.time
     };
 
+    /**
+     * @member {Object} target
+     * @memberof OpenSeadragon.Spring#
+     * @property {Number} value
+     * @property {Number} time
+     */
     this.target = {
         value: this.current.value,
         time:  this.current.time
     };
 };
 
-$.Spring.prototype = {
+$.Spring.prototype = /** @lends OpenSeadragon.Spring.prototype */{
 
     /**
      * @function

src/strings.js

@@ -59,11 +59,10 @@ var I18N = {
     }
 };
 
-$.extend( $, {
+$.extend( $, /** @lends OpenSeadragon */{
 
     /**
      * @function
-     * @name OpenSeadragon.getString
      * @param {String} property
      */
     getString: function( prop ) {
@@ -95,7 +94,6 @@ $.extend( $, {
 
     /**
      * @function
-     * @name OpenSeadragon.setString
      * @param {String} property
      * @param {*} value
      */

src/tile.js

@@ -35,7 +35,8 @@
 (function( $ ){
     var TILE_CACHE       = {};
 /**
- * @class
+ * @class Tile
+ * @memberof OpenSeadragon
  * @param {Number} level The zoom level this tile belongs to.
  * @param {Number} x The vector component 'x'.
  * @param {Number} y The vector component 'y'.
@@ -44,57 +45,134 @@
  * @param {Boolean} exists Is this tile a part of a sparse image? ( Also has
  *      this tile failed to load? )
  * @param {String} url The URL of this tile's image.
- *
- * @property {Number} level The zoom level this tile belongs to.
- * @property {Number} x The vector component 'x'.
- * @property {Number} y The vector component 'y'.
- * @property {OpenSeadragon.Point} bounds Where this tile fits, in normalized
- *      coordinates
- * @property {Boolean} exists Is this tile a part of a sparse image? ( Also has
- *      this tile failed to load?
- * @property {String} url The URL of this tile's image.
- * @property {Boolean} loaded Is this tile loaded?
- * @property {Boolean} loading Is this tile loading?
- * @property {Element} element The HTML div element for this tile
- * @property {Element} imgElement The HTML img element for this tile
- * @property {Image} image The Image object for this tile
- * @property {String} style The alias of this.element.style.
- * @property {String} position This tile's position on screen, in pixels.
- * @property {String} size This tile's size on screen, in pixels
- * @property {String} blendStart The start time of this tile's blending
- * @property {String} opacity The current opacity this tile should be.
- * @property {String} distance The distance of this tile to the viewport center
- * @property {String} visibility The visibility score of this tile.
- * @property {Boolean} beingDrawn Whether this tile is currently being drawn
- * @property {Number} lastTouchTime Timestamp the tile was last touched.
  */
 $.Tile = function(level, x, y, bounds, exists, url) {
+    /**
+     * The zoom level this tile belongs to.
+     * @member {Number} level
+     * @memberof OpenSeadragon.Tile#
+     */
     this.level   = level;
+    /**
+     * The vector component 'x'.
+     * @member {Number} x
+     * @memberof OpenSeadragon.Tile#
+     */
     this.x       = x;
+    /**
+     * The vector component 'y'.
+     * @member {Number} y
+     * @memberof OpenSeadragon.Tile#
+     */
     this.y       = y;
+    /**
+     * Where this tile fits, in normalized coordinates
+     * @member {OpenSeadragon.Point} bounds
+     * @memberof OpenSeadragon.Tile#
+     */
     this.bounds  = bounds;
+    /**
+     * Is this tile a part of a sparse image? Also has this tile failed to load?
+     * @member {Boolean} exists
+     * @memberof OpenSeadragon.Tile#
+     */
     this.exists  = exists;
+    /**
+     * The URL of this tile's image.
+     * @member {String} url
+     * @memberof OpenSeadragon.Tile#
+     */
     this.url     = url;
+    /**
+     * Is this tile loaded?
+     * @member {Boolean} loaded
+     * @memberof OpenSeadragon.Tile#
+     */
     this.loaded  = false;
+    /**
+     * Is this tile loading?
+     * @member {Boolean} loading
+     * @memberof OpenSeadragon.Tile#
+     */
     this.loading = false;
 
+    /**
+     * The HTML div element for this tile
+     * @member {Element} element
+     * @memberof OpenSeadragon.Tile#
+     */
     this.element    = null;
+    /**
+     * The HTML img element for this tile.
+     * @member {Element} imgElement
+     * @memberof OpenSeadragon.Tile#
+     */
     this.imgElement = null;
+    /**
+     * The Image object for this tile.
+     * @member {Object} image
+     * @memberof OpenSeadragon.Tile#
+     */
     this.image      = null;
 
+    /**
+     * The alias of this.element.style.
+     * @member {String} style
+     * @memberof OpenSeadragon.Tile#
+     */
     this.style      = null;
+    /**
+     * This tile's position on screen, in pixels.
+     * @member {OpenSeadragon.Point} position
+     * @memberof OpenSeadragon.Tile#
+     */
     this.position   = null;
+    /**
+     * This tile's size on screen, in pixels.
+     * @member {OpenSeadragon.Point} size
+     * @memberof OpenSeadragon.Tile#
+     */
     this.size       = null;
+    /**
+     * The start time of this tile's blending.
+     * @member {Number} blendStart
+     * @memberof OpenSeadragon.Tile#
+     */
     this.blendStart = null;
+    /**
+     * The current opacity this tile should be.
+     * @member {Number} opacity
+     * @memberof OpenSeadragon.Tile#
+     */
     this.opacity    = null;
+    /**
+     * The distance of this tile to the viewport center.
+     * @member {Number} distance
+     * @memberof OpenSeadragon.Tile#
+     */
     this.distance   = null;
+    /**
+     * The visibility score of this tile.
+     * @member {Number} visibility
+     * @memberof OpenSeadragon.Tile#
+     */
     this.visibility = null;
 
+    /**
+     * Whether this tile is currently being drawn.
+     * @member {Boolean} beingDrawn
+     * @memberof OpenSeadragon.Tile#
+     */
     this.beingDrawn     = false;
+    /**
+     * Timestamp the tile was last touched.
+     * @member {Number} lastTouchTime
+     * @memberof OpenSeadragon.Tile#
+     */
     this.lastTouchTime  = 0;
 };
 
-$.Tile.prototype = {
+$.Tile.prototype = /** @lends OpenSeadragon.Tile.prototype */{
 
     /**
      * Provides a string representation of this tiles level and (x,y)

src/tilesource.js

@@ -36,7 +36,8 @@
 
 
 /**
- * The TileSource contains the most basic implementation required to create a
+ * @class TileSource
+ * @classdesc The TileSource contains the most basic implementation required to create a
  * smooth transition between layer in an image pyramid. It has only a single key
  * interface that must be implemented to complete it key functionality:
  * 'getTileUrl'.  It also has several optional interfaces that can be
@@ -48,7 +49,8 @@
  * By default the image pyramid is split into N layers where the images longest
  * side in M (in pixels), where N is the smallest integer which satisfies
  *      <strong>2^(N+1) >= M</strong>.
- * @class
+ *
+ * @memberof OpenSeadragon
  * @extends OpenSeadragon.EventSource
  * @param {Number|Object|Array|String} width
  *      If more than a single argument is supplied, the traditional use of
@@ -70,18 +72,6 @@
  *      The minimum level to attempt to load.
  * @param {Number} maxLevel
  *      The maximum level to attempt to load.
- * @property {Number} aspectRatio
- *      Ratio of width to height
- * @property {OpenSeadragon.Point} dimensions
- *      Vector storing x and y dimensions ( width and height respectively ).
- * @property {Number} tileSize
- *      The size of the image tiles used to compose the image.
- * @property {Number} tileOverlap
- *      The overlap in pixels each tile shares with it's adjacent neighbors.
- * @property {Number} minLevel
- *      The minimum pyramid level this tile source supports or should attempt to load.
- * @property {Number} maxLevel
- *      The maximum pyramid level this tile source supports or should attempt to load.
  */
 $.TileSource = function( width, height, tileSize, tileOverlap, minLevel, maxLevel ) {
     var callback = null,
@@ -125,6 +115,42 @@ $.TileSource = function( width, height, tileSize, tileOverlap, minLevel, maxLeve
         }
     }
 
+    /**
+     * Ratio of width to height
+     * @member {Number} aspectRatio
+     * @memberof OpenSeadragon.TileSource#
+     */
+    /**
+     * Vector storing x and y dimensions ( width and height respectively ).
+     * @member {OpenSeadragon.Point} dimensions
+     * @memberof OpenSeadragon.TileSource#
+     */
+    /**
+     * The size of the image tiles used to compose the image.
+     * @member {Number} tileSize
+     * @memberof OpenSeadragon.TileSource#
+     */
+    /**
+     * The overlap in pixels each tile shares with it's adjacent neighbors.
+     * @member {Number} tileOverlap
+     * @memberof OpenSeadragon.TileSource#
+     */
+    /**
+     * The minimum pyramid level this tile source supports or should attempt to load.
+     * @member {Number} minLevel
+     * @memberof OpenSeadragon.TileSource#
+     */
+    /**
+     * The maximum pyramid level this tile source supports or should attempt to load.
+     * @member {Number} maxLevel
+     * @memberof OpenSeadragon.TileSource#
+     */
+    /**
+     * 
+     * @member {Boolean} ready
+     * @memberof OpenSeadragon.TileSource#
+     */
+
     if( 'string' == $.type( arguments[ 0 ] ) ){
         //in case the getImageInfo method is overriden and/or implies an
         //async mechanism set some safe defaults first
@@ -166,7 +192,7 @@ $.TileSource = function( width, height, tileSize, tileOverlap, minLevel, maxLeve
 };
 
 
-$.TileSource.prototype = {
+$.TileSource.prototype = /** @lends OpenSeadragon.TileSource.prototype */{
 
     /**
      * @function
@@ -297,6 +323,17 @@ $.TileSource.prototype = {
             }
             var $TileSource = $.TileSource.determineType( _this, data, url );
             if ( !$TileSource ) {
+                /**
+                 * Raised when an error occurs loading a TileSource.
+                 *
+                 * @event open-failed
+                 * @memberof OpenSeadragon.TileSource
+                 * @type {object}
+                 * @property {OpenSeadragon.TileSource} eventSource - A reference to the TileSource which raised the event.
+                 * @property {String} message
+                 * @property {String} source
+                 * @property {?Object} userData - Arbitrary subscriber-defined object.
+                 */
                 _this.raiseEvent( 'open-failed', { message: "Unable to load TileSource", source: url } );
                 return;
             }
@@ -304,6 +341,16 @@ $.TileSource.prototype = {
             options = $TileSource.prototype.configure.apply( _this, [ data, url ]);
             readySource = new $TileSource( options );
             _this.ready = true;
+            /**
+             * Raised when a TileSource is opened and initialized.
+             *
+             * @event ready
+             * @memberof OpenSeadragon.TileSource
+             * @type {object}
+             * @property {OpenSeadragon.TileSource} eventSource - A reference to the TileSource which raised the event.
+             * @property {Object} tileSource
+             * @property {?Object} userData - Arbitrary subscriber-defined object.
+             */
             _this.raiseEvent( 'ready', { tileSource: readySource } );
         };
 
@@ -344,6 +391,17 @@ $.TileSource.prototype = {
                     msg = formattedExc + " attempting to load TileSource";
                 }
 
+                /***
+                 * Raised when an error occurs loading a TileSource.
+                 *
+                 * @event open-failed
+                 * @memberof OpenSeadragon.TileSource
+                 * @type {object}
+                 * @property {OpenSeadragon.TileSource} eventSource - A reference to the TileSource which raised the event.
+                 * @property {String} message
+                 * @property {String} source
+                 * @property {?Object} userData - Arbitrary subscriber-defined object.
+                 */
                 _this.raiseEvent( 'open-failed', {
                     message: msg,
                     source: url
@@ -431,7 +489,7 @@ $.extend( true, $.TileSource.prototype, $.EventSource.prototype );
 /**
  * Decides whether to try to process the response as xml, json, or hand back
  * the text
- * @eprivate
+ * @private
  * @inner
  * @function
  * @param {XMLHttpRequest} xhr - the completed network request
@@ -473,7 +531,7 @@ function processResponse( xhr ){
 /**
  * Determines the TileSource Implementation by introspection of OpenSeadragon
  * namespace, calling each TileSource implementation of 'isType'
- * @eprivate
+ * @private
  * @inner
  * @function
  * @param {Object|Array|Document} data - the tile source configuration object

src/tilesourcecollection.js

@@ -35,7 +35,8 @@
 (function( $ ){
 
 /**
- * @class
+ * @class TileSourceCollection
+ * @memberof OpenSeadragon
  * @extends OpenSeadragon.TileSource
  */
 $.TileSourceCollection = function( tileSize, tileSources, rows, layout  ) {
@@ -92,11 +93,10 @@ $.TileSourceCollection = function( tileSize, tileSources, rows, layout  ) {
 
 };
 
-$.extend( $.TileSourceCollection.prototype, $.TileSource.prototype, {
+$.extend( $.TileSourceCollection.prototype, $.TileSource.prototype, /** @lends OpenSeadragon.TileSourceCollection.prototype */{
 
     /**
      * @function
-     * @name OpenSeadragon.TileSourceCollection.prototype.getTileBounds
      * @param {Number} level
      * @param {Number} x
      * @param {Number} y
@@ -118,7 +118,6 @@ $.extend( $.TileSourceCollection.prototype, $.TileSource.prototype, {
     /**
      *
      * @function
-     * @name OpenSeadragon.TileSourceCollection.prototype.configure
      */
     configure: function( data, url ){
         return;
@@ -127,7 +126,6 @@ $.extend( $.TileSourceCollection.prototype, $.TileSource.prototype, {
 
     /**
      * @function
-     * @name OpenSeadragon.TileSourceCollection.prototype.getTileUrl
      * @param {Number} level
      * @param {Number} x
      * @param {Number} y

src/tmstilesource.js

@@ -43,11 +43,12 @@
 (function( $ ){
 
 /**
- * A tilesource implementation for Tiled Map Services (TMS).
+ * @class TmsTileSource
+ * @classdesc A tilesource implementation for Tiled Map Services (TMS).
  * TMS tile scheme ( [ as supported by OpenLayers ] is described here
  * ( http://openlayers.org/dev/examples/tms.html ).
  *
- * @class
+ * @memberof OpenSeadragon
  * @extends OpenSeadragon.TileSource
  * @param {Number|Object} width - the pixel width of the image or the idiomatic
  *      options object which is used instead of positional arguments.
@@ -91,14 +92,13 @@ $.TmsTileSource = function( width, height, tileSize, tileOverlap, tilesUrl ) {
 
 };
 
-$.extend( $.TmsTileSource.prototype, $.TileSource.prototype, {
+$.extend( $.TmsTileSource.prototype, $.TileSource.prototype, /** @lends OpenSeadragon.TmsTileSource.prototype */{
 
 
     /**
      * Determine if the data and/or url imply the image service is supported by
      * this tile source.
      * @function
-     * @name OpenSeadragon.TmsTileSource.prototype.supports
      * @param {Object|Array} data
      * @param {String} optional - url
      */
@@ -109,7 +109,6 @@ $.extend( $.TmsTileSource.prototype, $.TileSource.prototype, {
     /**
      *
      * @function
-     * @name OpenSeadragon.TmsTileSource.prototype.configure
      * @param {Object} data - the raw configuration
      * @param {String} url - the url the data was retreived from if any.
      * @return {Object} options - A dictionary of keyword arguments sufficient
@@ -122,7 +121,6 @@ $.extend( $.TmsTileSource.prototype, $.TileSource.prototype, {
 
     /**
      * @function
-     * @name OpenSeadragon.TmsTileSource.prototype.getTileUrl
      * @param {Number} level
      * @param {Number} x
      * @param {Number} y

src/viewer.js

@@ -50,20 +50,13 @@ var THIS = {},
  * The options below are given in order that they appeared in the constructor
  * as arguments and we translate a positional call into an idiomatic call.
  *
- * @class
+ * @class Viewer
+ * @classdesc The main OpenSeadragon viewer class.
+ *
+ * @memberof OpenSeadragon
  * @extends OpenSeadragon.EventSource
  * @extends OpenSeadragon.ControlDock
- * @param {Object} options
+ * @param {OpenSeadragon.Options} options - Viewer options.
- * @param {String} options.element Id of Element to attach to,
- * @param {String} options.xmlPath  Xpath ( TODO: not sure! ),
- * @param {String} options.prefixUrl  Url used to prepend to paths, eg button
- *  images, etc.
- * @param {OpenSeadragon.Control[]} options.controls Array of OpenSeadragon.Control,
- * @param {OpenSeadragon.Overlay[]} options.overlays Array of OpenSeadragon.Overlay,
- * @param {OpenSeadragon.Control[]} options.overlayControls An Array of ( TODO:
- *  not sure! )
- * @property {OpenSeadragon.Viewport} viewport The viewer's viewport, where you
- *  can access zoom, pan, etc.
  *
  **/
 $.Viewer = function( options ) {
@@ -103,9 +96,36 @@ $.Viewer = function( options ) {
         hash:           options.hash || options.id,
 
         //dom nodes
+        /**
+         * The parent element of this Viewer instance, passed in when the Viewer was created.
+         * @member {Element} element
+         * @memberof OpenSeadragon.Viewer#
+         */
         element:        null,
-        canvas:         null,
+        /**
+         * A &lt;form&gt; element (provided by {@link OpenSeadragon.ControlDock}), the base element of this Viewer instance.<br><br>
+         * Child element of {@link OpenSeadragon.Viewer#element}.
+         * @member {Element} container
+         * @memberof OpenSeadragon.Viewer#
+         */
         container:      null,
+        /**
+         * A &lt;textarea&gt; element, the element where keyboard events are handled.<br><br>
+         * Child element of {@link OpenSeadragon.Viewer#container},
+         * positioned below {@link OpenSeadragon.Viewer#canvas}. 
+         * @member {Element} keyboardCommandArea
+         * @memberof OpenSeadragon.Viewer#
+         */
+        keyboardCommandArea: null,
+        /**
+         * A &lt;div&gt; element, the element where user-input events are handled for panning and zooming.<br><br>
+         * Child element of {@link OpenSeadragon.Viewer#container},
+         * positioned on top of {@link OpenSeadragon.Viewer#keyboardCommandArea}.<br><br>
+         * The parent of {@link OpenSeadragon.Drawer#canvas} instances. 
+         * @member {Element} canvas
+         * @memberof OpenSeadragon.Viewer#
+         */
+        canvas:         null,
 
         //TODO: not sure how to best describe these
         overlays:       [],
@@ -123,15 +143,29 @@ $.Viewer = function( options ) {
         customControls: [],
 
         //These are originally not part options but declared as members
-        //in initialize.  Its still considered idiomatic to put them here
+        //in initialize.  It's still considered idiomatic to put them here
         source:         null,
+        /**
+         * Handles rendering of tiles in the viewer. Created for each TileSource opened.
+         * @member {OpenSeadragon.Drawer} drawer
+         * @memberof OpenSeadragon.Viewer#
+         */
         drawer:         null,
         drawers:        [],
+        /**
+         * Handles coordinate-related functionality - zoom, pan, rotation, etc. Created for each TileSource opened.
+         * @member {OpenSeadragon.Viewport} viewport
+         * @memberof OpenSeadragon.Viewer#
+         */
         viewport:       null,
+        /**
+         * @member {OpenSeadragon.Navigator} navigator
+         * @memberof OpenSeadragon.Viewer#
+         */
         navigator:      null,
 
-        //A collection viewport is a seperate viewport used to provide
+        //A collection viewport is a separate viewport used to provide
-        //simultanious rendering of sets of tiless
+        //simultaneous rendering of sets of tiles
         collectionViewport:     null,
         collectionDrawer:       null,
 
@@ -384,12 +418,11 @@ $.Viewer = function( options ) {
 
 };
 
-$.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, {
+$.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, /** @lends OpenSeadragon.Viewer.prototype */{
 
 
     /**
      * @function
-     * @name OpenSeadragon.Viewer.prototype.isOpen
      * @return {Boolean}
      */
     isOpen: function () {
@@ -400,11 +433,10 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
      * A deprecated function, renamed to 'open' to match event name and
      * match current 'close' method.
      * @function
-     * @name OpenSeadragon.Viewer.prototype.openDzi
      * @param {String} dzi xml string or the url to a DZI xml document.
      * @return {OpenSeadragon.Viewer} Chainable.
      *
-     * @deprecated - use 'open' instead.
+     * @deprecated - use {@link OpenSeadragon.Viewer#open} instead.
      */
     openDzi: function ( dzi ) {
         return this.open( dzi );
@@ -414,11 +446,10 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
      * A deprecated function, renamed to 'open' to match event name and
      * match current 'close' method.
      * @function
-     * @name OpenSeadragon.Viewer.prototype.openTileSource
      * @param {String|Object|Function} See OpenSeadragon.Viewer.prototype.open
      * @return {OpenSeadragon.Viewer} Chainable.
      *
-     * @deprecated - use 'open' instead.
+     * @deprecated - use {@link OpenSeadragon.Viewer#open} instead.
      */
     openTileSource: function ( tileSource ) {
         return this.open( tileSource );
@@ -440,9 +471,10 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
      *      implementation. If the object has a property which is a function
      *      named 'getTileUrl', it is treated as a custom TileSource.
      * @function
-     * @name OpenSeadragon.Viewer.prototype.open
      * @param {String|Object|Function}
      * @return {OpenSeadragon.Viewer} Chainable.
+     * @fires OpenSeadragon.Viewer.event:open
+     * @fires OpenSeadragon.Viewer.event:open-failed
      */
     open: function ( tileSource ) {
         var _this = this,
@@ -470,6 +502,17 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
                     openTileSource( _this, event.tileSource );
                 });
                 tileSource.addHandler( 'open-failed', function ( event ) {
+                    /**
+                     * Raised when an error occurs loading a TileSource.
+                     *
+                     * @event open-failed
+                     * @memberof OpenSeadragon.Viewer
+                     * @type {object}
+                     * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event.
+                     * @property {String} message
+                     * @property {String} source
+                     * @property {?Object} userData - Arbitrary subscriber-defined object.
+                     */
                     _this.raiseEvent( 'open-failed', event );
                 });
 
@@ -483,6 +526,17 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
                     //inline configuration
                     $TileSource = $.TileSource.determineType( _this, tileSource );
                     if ( !$TileSource ) {
+                        /***
+                         * Raised when an error occurs loading a TileSource.
+                         *
+                         * @event open-failed
+                         * @memberof OpenSeadragon.Viewer
+                         * @type {object}
+                         * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event.
+                         * @property {String} message
+                         * @property {String} source
+                         * @property {?Object} userData - Arbitrary subscriber-defined object.
+                         */
                         _this.raiseEvent( 'open-failed', {
                             message: "Unable to load TileSource",
                             source: tileSource
@@ -505,8 +559,8 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
 
     /**
      * @function
-     * @name OpenSeadragon.Viewer.prototype.close
      * @return {OpenSeadragon.Viewer} Chainable.
+     * @fires OpenSeadragon.Viewer.event:close
      */
     close: function ( ) {
         if ( this._updateRequestId !== null ) {
@@ -534,6 +588,15 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
         VIEWERS[ this.hash ] = null;
         delete VIEWERS[ this.hash ];
 
+        /**
+         * Raised when the viewer is closed (see {@link OpenSeadragon.Viewer#close}).
+         *
+         * @event close
+         * @memberof OpenSeadragon.Viewer
+         * @type {object}
+         * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event.
+         * @property {?Object} userData - Arbitrary subscriber-defined object.
+         */
         this.raiseEvent( 'close' );
 
         return this;
@@ -544,7 +607,6 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
      * Function to destroy the viewer and clean up everything created by
      * OpenSeadragon.
      * @function
-     * @name OpenSeadragon.Viewer.prototype.destroy
      */
     destroy: function( ) {
         this.close();
@@ -583,7 +645,6 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
 
     /**
      * @function
-     * @name OpenSeadragon.Viewer.prototype.isMouseNavEnabled
      * @return {Boolean}
      */
     isMouseNavEnabled: function () {
@@ -592,11 +653,22 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
 
     /**
      * @function
-     * @name OpenSeadragon.Viewer.prototype.setMouseNavEnabled
+     * @param {Boolean} enabled - true to enable, false to disable
      * @return {OpenSeadragon.Viewer} Chainable.
+     * @fires OpenSeadragon.Viewer.event:mouse-enabled
      */
     setMouseNavEnabled: function( enabled ){
         this.innerTracker.setTracking( enabled );
+        /**
+         * Raised when mouse/touch navigation is enabled or disabled (see {@link OpenSeadragon.Viewer#setMouseNavEnabled}).
+         *
+         * @event mouse-enabled
+         * @memberof OpenSeadragon.Viewer
+         * @type {object}
+         * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event.
+         * @property {Boolean} enabled
+         * @property {?Object} userData - Arbitrary subscriber-defined object.
+         */
         this.raiseEvent( 'mouse-enabled', { enabled: enabled } );
         return this;
     },
@@ -604,7 +676,6 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
 
     /**
      * @function
-     * @name OpenSeadragon.Viewer.prototype.areControlsEnabled
      * @return {Boolean}
      */
     areControlsEnabled: function () {
@@ -621,9 +692,9 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
      * Shows or hides the controls (e.g. the default navigation buttons).
      *
      * @function
-     * @name OpenSeadragon.Viewer.prototype.setControlsEnabled
      * @param {Boolean} true to show, false to hide.
      * @return {OpenSeadragon.Viewer} Chainable.
+     * @fires OpenSeadragon.Viewer.event:controls-enabled
      */
     setControlsEnabled: function( enabled ) {
         if( enabled ){
@@ -631,6 +702,16 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
         } else {
             beginControlsAutoHide( this );
         }
+        /**
+         * Raised when the navigation controls are shown or hidden (see {@link OpenSeadragon.Viewer#setControlsEnabled}).
+         *
+         * @event controls-enabled
+         * @memberof OpenSeadragon.Viewer
+         * @type {object}
+         * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event.
+         * @property {Boolean} enabled
+         * @property {?Object} userData - Arbitrary subscriber-defined object.
+         */
         this.raiseEvent( 'controls-enabled', { enabled: enabled } );
         return this;
     },
@@ -638,7 +719,6 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
 
     /**
      * @function
-     * @name OpenSeadragon.Viewer.prototype.isFullPage
      * @return {Boolean}
      */
     isFullPage: function () {
@@ -649,10 +729,11 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
     /**
      * Toggle full page mode.
      * @function
-     * @name OpenSeadragon.Viewer.prototype.setFullPage
      * @param {Boolean} fullPage
      *      If true, enter full page mode.  If false, exit full page mode.
      * @return {OpenSeadragon.Viewer} Chainable.
+     * @fires OpenSeadragon.Viewer.event:pre-full-page
+     * @fires OpenSeadragon.Viewer.event:full-page
      */
     setFullPage: function( fullPage ) {
 
@@ -673,6 +754,17 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
             fullPage: fullPage,
             preventDefaultAction: false
         };
+        /**
+         * Raised when the viewer is about to change to/from full-page mode (see {@link OpenSeadragon.Viewer#setFullPage}).
+         *
+         * @event pre-full-page
+         * @memberof OpenSeadragon.Viewer
+         * @type {object}
+         * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event.
+         * @property {Boolean} fullPage - True if entering full-page mode, false if exiting full-page mode.
+         * @property {Boolean} preventDefaultAction - Set to true to prevent full-page mode change. Default: false.
+         * @property {?Object} userData - Arbitrary subscriber-defined object.
+         */
         this.raiseEvent( 'pre-full-page', fullPageEventArgs );
         if ( fullPageEventArgs.preventDefaultAction ) {
             return this;
@@ -818,6 +910,16 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
 
         }
 
+        /**
+         * Raised when the viewer has changed to/from full-page mode (see {@link OpenSeadragon.Viewer#setFullPage}).
+         *
+         * @event full-page
+         * @memberof OpenSeadragon.Viewer
+         * @type {object}
+         * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event.
+         * @property {Boolean} fullPage - True if changed to full-page mode, false if exited full-page mode.
+         * @property {?Object} userData - Arbitrary subscriber-defined object.
+         */
         this.raiseEvent( 'full-page', { fullPage: fullPage } );
 
         return this;
@@ -826,10 +928,11 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
     /**
      * Toggle full screen mode if supported. Toggle full page mode otherwise.
      * @function
-     * @name OpenSeadragon.Viewer.prototype.setFullScreen
      * @param {Boolean} fullScreen
      *      If true, enter full screen mode.  If false, exit full screen mode.
      * @return {OpenSeadragon.Viewer} Chainable.
+     * @fires OpenSeadragon.Viewer.event:pre-full-screen
+     * @fires OpenSeadragon.Viewer.event:full-screen
      */
     setFullScreen: function( fullScreen ) {
         var _this = this;
@@ -846,6 +949,17 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
             fullScreen: fullScreen,
             preventDefaultAction: false
         };
+        /**
+         * Raised when the viewer is about to change to/from full-screen mode (see {@link OpenSeadragon.Viewer#setFullScreen}).
+         *
+         * @event pre-full-screen
+         * @memberof OpenSeadragon.Viewer
+         * @type {object}
+         * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event.
+         * @property {Boolean} fullScreen - True if entering full-screen mode, false if exiting full-screen mode.
+         * @property {Boolean} preventDefaultAction - Set to true to prevent full-screen mode change. Default: false.
+         * @property {?Object} userData - Arbitrary subscriber-defined object.
+         */
         this.raiseEvent( 'pre-full-screen', fullScreeEventArgs );
         if ( fullScreeEventArgs.preventDefaultAction ) {
             return this;
@@ -877,6 +991,16 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
                         _this.element.style.height = _this.fullPageStyleHeight;
                     }
                 }
+                /**
+                 * Raised when the viewer has changed to/from full-screen mode (see {@link OpenSeadragon.Viewer#setFullScreen}).
+                 *
+                 * @event full-screen
+                 * @memberof OpenSeadragon.Viewer
+                 * @type {object}
+                 * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event.
+                 * @property {Boolean} fullScreen - True if changed to full-screen mode, false if exited full-screen mode.
+                 * @property {?Object} userData - Arbitrary subscriber-defined object.
+                 */
                 _this.raiseEvent( 'full-screen', { fullScreen: isFullScreen } );
             };
             $.addEvent( document, $.fullScreenEventName, onFullScreenChange );
@@ -892,7 +1016,6 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
 
     /**
      * @function
-     * @name OpenSeadragon.Viewer.prototype.isVisible
      * @return {Boolean}
      */
     isVisible: function () {
@@ -902,11 +1025,22 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
 
     /**
      * @function
-     * @name OpenSeadragon.Viewer.prototype.setVisible
+     * @param {Boolean} visible
      * @return {OpenSeadragon.Viewer} Chainable.
+     * @fires OpenSeadragon.Viewer.event:visible
      */
     setVisible: function( visible ){
         this.container.style.visibility = visible ? "" : "hidden";
+        /**
+         * Raised when the viewer is shown or hidden (see {@link OpenSeadragon.Viewer#setVisible}).
+         *
+         * @event visible
+         * @memberof OpenSeadragon.Viewer
+         * @type {object}
+         * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event.
+         * @property {Boolean} visible
+         * @property {?Object} userData - Arbitrary subscriber-defined object.
+         */
         this.raiseEvent( 'visible', { visible: visible } );
         return this;
     },
@@ -914,7 +1048,6 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
 
     /**
      * @function
-     * @name OpenSeadragon.Viewer.prototype.bindSequenceControls
      * @return {OpenSeadragon.Viewer} Chainable.
      */
     bindSequenceControls: function(){
@@ -1000,7 +1133,6 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
 
     /**
      * @function
-     * @name OpenSeadragon.Viewer.prototype.bindStandardControls
      * @return {OpenSeadragon.Viewer} Chainable.
      */
     bindStandardControls: function(){
@@ -1123,7 +1255,6 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
     /**
      * Gets the active page of a sequence
      * @function
-     * @name OpenSeadragon.Viewer.prototype.currentPage
      * @return {Number}
      */
     currentPage: function () {
@@ -1132,13 +1263,13 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
 
     /**
      * @function
-     * @name OpenSeadragon.Viewer.prototype.goToPage
      * @return {OpenSeadragon.Viewer} Chainable.
+     * @fires OpenSeadragon.Viewer.event:page
      */
     goToPage: function( page ){
         if( page >= 0 && page < this.tileSources.length ){
             /**
-             * Raised when the page is changed on a viewer configured with multiple image sources.
+             * Raised when the page is changed on a viewer configured with multiple image sources (see {@link OpenSeadragon.Viewer#goToPage}).
              *
              * @event page
              * @memberof OpenSeadragon.Viewer
@@ -1165,7 +1296,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
 
     /**
      * Updates the sequence buttons.
-     * @function
+     * @function OpenSeadragon.Viewer.prototype._updateSequenceButtons
      * @private
      * @param {Number} Sequence Value
      */
@@ -1195,7 +1326,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
       
     /**
      * Display a message in the viewport
-     * @function
+     * @function OpenSeadragon.Viewer.prototype._showMessage
      * @private
      * @param {String} text message
      */
@@ -1214,7 +1345,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
 
     /**
      * Hide any currently displayed viewport message
-     * @function
+     * @function OpenSeadragon.Viewer.prototype._hideMessage
      * @private
      */
     _hideMessage: function () {
@@ -1409,6 +1540,16 @@ function openTileSource( viewer, source ) {
     }
     VIEWERS[ _this.hash ] = _this;
 
+    /**
+     * Raised when the viewer has opened and loaded one or more TileSources.
+     *
+     * @event open
+     * @memberof OpenSeadragon.Viewer
+     * @type {object}
+     * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event.
+     * @property {OpenSeadragon.TileSource} source
+     * @property {?Object} userData - Arbitrary subscriber-defined object.
+     */
     _this.raiseEvent( 'open', { source: source } );
 
     return _this;
@@ -1514,6 +1655,20 @@ function onCanvasClick( event ) {
         );
         this.viewport.applyConstraints();
     }
+    /**
+     * Raised when a mouse press/release or touch/remove occurs on the {@link OpenSeadragon.Viewer#canvas} element.
+     *
+     * @event canvas-click
+     * @memberof OpenSeadragon.Viewer
+     * @type {object}
+     * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event.
+     * @property {OpenSeadragon.MouseTracker} tracker - A reference to the MouseTracker which originated this event.
+     * @property {OpenSeadragon.Point} position - The position of the event relative to the tracked element.
+     * @property {Boolean} quick - True only if the clickDistThreshold and clickDeltaThreshold are both passed. Useful for differentiating between clicks and drags.
+     * @property {Boolean} shift - True if the shift key was pressed during this event.
+     * @property {Object} originalEvent - The original DOM event.
+     * @property {?Object} userData - Arbitrary subscriber-defined object.
+     */
     this.raiseEvent( 'canvas-click', {
         tracker: event.eventSource,
         position: event.position,
@@ -1540,6 +1695,20 @@ function onCanvasDrag( event ) {
             this.viewport.applyConstraints();
         }
     }
+    /**
+     * Raised when a mouse or touch drag operation occurs on the {@link OpenSeadragon.Viewer#canvas} element.
+     *
+     * @event canvas-drag
+     * @memberof OpenSeadragon.Viewer
+     * @type {object}
+     * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event.
+     * @property {OpenSeadragon.MouseTracker} tracker - A reference to the MouseTracker which originated this event.
+     * @property {OpenSeadragon.Point} position - The position of the event relative to the tracked element.
+     * @property {OpenSeadragon.Point} delta - The x,y components of the difference between start drag and end drag.
+     * @property {Boolean} shift - True if the shift key was pressed during this event.
+     * @property {Object} originalEvent - The original DOM event.
+     * @property {?Object} userData - Arbitrary subscriber-defined object.
+     */
     this.raiseEvent( 'canvas-drag', {
         tracker: event.eventSource,
         position: event.position,
@@ -1553,6 +1722,20 @@ function onCanvasRelease( event ) {
     if ( event.insideElementPressed && this.viewport ) {
         this.viewport.applyConstraints();
     }
+    /**
+     * Raised when the mouse button is released or touch ends on the {@link OpenSeadragon.Viewer#canvas} element.
+     *
+     * @event canvas-release
+     * @memberof OpenSeadragon.Viewer
+     * @type {object}
+     * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event.
+     * @property {OpenSeadragon.MouseTracker} tracker - A reference to the MouseTracker which originated this event.
+     * @property {OpenSeadragon.Point} position - The position of the event relative to the tracked element.
+     * @property {Boolean} insideElementPressed - True if the left mouse button is currently being pressed and was initiated inside the tracked element, otherwise false.
+     * @property {Boolean} insideElementReleased - True if the cursor still inside the tracked element when the button was released.
+     * @property {Object} originalEvent - The original DOM event.
+     * @property {?Object} userData - Arbitrary subscriber-defined object.
+     */
     this.raiseEvent( 'canvas-release', {
         tracker: event.eventSource,
         position: event.position,
@@ -1572,6 +1755,20 @@ function onCanvasScroll( event ) {
         );
         this.viewport.applyConstraints();
     }
+    /**
+     * Raised when a scroll event occurs on the {@link OpenSeadragon.Viewer#canvas} element (mouse wheel, touch pinch, etc.).
+     *
+     * @event canvas-scroll
+     * @memberof OpenSeadragon.Viewer
+     * @type {object}
+     * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event.
+     * @property {OpenSeadragon.MouseTracker} tracker - A reference to the MouseTracker which originated this event.
+     * @property {OpenSeadragon.Point} position - The position of the event relative to the tracked element.
+     * @property {Number} scroll - The scroll delta for the event.
+     * @property {Boolean} shift - True if the shift key was pressed during this event.
+     * @property {Object} originalEvent - The original DOM event.
+     * @property {?Object} userData - Arbitrary subscriber-defined object.
+     */
     this.raiseEvent( 'canvas-scroll', {
         tracker: event.eventSource,
         position: event.position,
@@ -1590,6 +1787,20 @@ function onContainerExit( event ) {
             beginControlsAutoHide( this );
         }
     }
+    /**
+     * Raised when the cursor leaves the {@link OpenSeadragon.Viewer#container} element.
+     *
+     * @event container-exit
+     * @memberof OpenSeadragon.Viewer
+     * @type {object}
+     * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event.
+     * @property {OpenSeadragon.MouseTracker} tracker - A reference to the MouseTracker which originated this event.
+     * @property {OpenSeadragon.Point} position - The position of the event relative to the tracked element.
+     * @property {Boolean} insideElementPressed - True if the left mouse button is currently being pressed and was initiated inside the tracked element, otherwise false.
+     * @property {Boolean} buttonDownAny - Was the button down anywhere in the screen during the event.
+     * @property {Object} originalEvent - The original DOM event.
+     * @property {?Object} userData - Arbitrary subscriber-defined object.
+     */
     this.raiseEvent( 'container-exit', {
         tracker: event.eventSource,
         position: event.position,
@@ -1606,6 +1817,20 @@ function onContainerRelease( event ) {
             beginControlsAutoHide( this );
         }
     }
+    /**
+     * Raised when the mouse button is released or touch ends on the {@link OpenSeadragon.Viewer#container} element.
+     *
+     * @event container-release
+     * @memberof OpenSeadragon.Viewer
+     * @type {object}
+     * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event.
+     * @property {OpenSeadragon.MouseTracker} tracker - A reference to the MouseTracker which originated this event.
+     * @property {OpenSeadragon.Point} position - The position of the event relative to the tracked element.
+     * @property {Boolean} insideElementPressed - True if the left mouse button is currently being pressed and was initiated inside the tracked element, otherwise false.
+     * @property {Boolean} insideElementReleased - True if the cursor still inside the tracked element when the button was released.
+     * @property {Object} originalEvent - The original DOM event.
+     * @property {?Object} userData - Arbitrary subscriber-defined object.
+     */
     this.raiseEvent( 'container-release', {
         tracker: event.eventSource,
         position: event.position,
@@ -1618,6 +1843,20 @@ function onContainerRelease( event ) {
 function onContainerEnter( event ) {
     THIS[ this.hash ].mouseInside = true;
     abortControlsAutoHide( this );
+    /**
+     * Raised when the cursor enters the {@link OpenSeadragon.Viewer#container} element.
+     *
+     * @event container-enter
+     * @memberof OpenSeadragon.Viewer
+     * @type {object}
+     * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event.
+     * @property {OpenSeadragon.MouseTracker} tracker - A reference to the MouseTracker which originated this event.
+     * @property {OpenSeadragon.Point} position - The position of the event relative to the tracked element.
+     * @property {Boolean} insideElementPressed - True if the left mouse button is currently being pressed and was initiated inside the tracked element, otherwise false.
+     * @property {Boolean} buttonDownAny - Was the button down anywhere in the screen during the event.
+     * @property {Object} originalEvent - The original DOM event.
+     * @property {?Object} userData - Arbitrary subscriber-defined object.
+     */
     this.raiseEvent( 'container-enter', {
         tracker: event.eventSource,
         position: event.position,
@@ -1676,6 +1915,15 @@ function updateOnce( viewer ) {
     }
 
     if ( !THIS[ viewer.hash ].animating && animated ) {
+        /**
+         * Raised when any spring animation starts (zoom, pan, etc.).
+         *
+         * @event animation-start
+         * @memberof OpenSeadragon.Viewer
+         * @type {object}
+         * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event.
+         * @property {?Object} userData - Arbitrary subscriber-defined object.
+         */
         viewer.raiseEvent( "animation-start" );
         abortControlsAutoHide( viewer );
     }
@@ -1685,6 +1933,15 @@ function updateOnce( viewer ) {
         if( viewer.navigator ){
             viewer.navigator.update( viewer.viewport );
         }
+        /**
+         * Raised when any spring animation update occurs (zoom, pan, etc.).
+         *
+         * @event animation
+         * @memberof OpenSeadragon.Viewer
+         * @type {object}
+         * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event.
+         * @property {?Object} userData - Arbitrary subscriber-defined object.
+         */
         viewer.raiseEvent( "animation" );
     } else if ( THIS[ viewer.hash ].forceRedraw || viewer.drawer.needsUpdate() ) {
         viewer.drawer.update();
@@ -1695,6 +1952,15 @@ function updateOnce( viewer ) {
     }
 
     if ( THIS[ viewer.hash ].animating && !animated ) {
+        /**
+         * Raised when any spring animation ends (zoom, pan, etc.).
+         *
+         * @event animation-finish
+         * @memberof OpenSeadragon.Viewer
+         * @type {object}
+         * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event.
+         * @property {?Object} userData - Arbitrary subscriber-defined object.
+         */
         viewer.raiseEvent( "animation-finish" );
 
         if ( !THIS[ viewer.hash ].mouseInside ) {

src/viewport.js

@@ -36,7 +36,11 @@
 
 
 /**
- * @class
+ * @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
  */
 $.Viewport = function( options ) {
 
@@ -105,11 +109,12 @@ $.Viewport = function( options ) {
     this.update();
 };
 
-$.Viewport.prototype = {
+$.Viewport.prototype = /** @lends OpenSeadragon.Viewport.prototype */{
 
     /**
      * @function
      * @return {OpenSeadragon.Viewport} Chainable.
+     * @fires OpenSeadragon.Viewer.event:reset-size
      */
     resetContentSize: function( contentSize ){
         this.contentSize    = contentSize;
@@ -121,6 +126,16 @@ $.Viewport.prototype = {
         this.homeBounds = new $.Rect( 0, 0, 1, this.contentAspectY );
 
         if( this.viewer ){
+            /**
+             * Raised when the viewer's content size is reset (see {@link OpenSeadragon.Viewport#resetContentSize}).
+             *
+             * @event reset-size
+             * @memberof OpenSeadragon.Viewer
+             * @type {object}
+             * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event.
+             * @property {OpenSeadragon.Point} contentSize
+             * @property {?Object} userData - Arbitrary subscriber-defined object.
+             */
             this.viewer.raiseEvent( 'reset-size', {
                 contentSize: contentSize
             });
@@ -164,9 +179,20 @@ $.Viewport.prototype = {
     /**
      * @function
      * @param {Boolean} immediately
+     * @fires OpenSeadragon.Viewer.event:home
      */
     goHome: function( immediately ) {
         if( this.viewer ){
+            /**
+             * Raised when the "home" operation occurs (see {@link OpenSeadragon.Viewport#goHome}).
+             *
+             * @event home
+             * @memberof OpenSeadragon.Viewer
+             * @type {object}
+             * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event.
+             * @property {Boolean} immediately
+             * @property {?Object} userData - Arbitrary subscriber-defined object.
+             */
             this.viewer.raiseEvent( 'home', {
                 immediately: immediately
             });
@@ -297,6 +323,7 @@ $.Viewport.prototype = {
     /**
      * @function
      * @return {OpenSeadragon.Viewport} Chainable.
+     * @fires OpenSeadragon.Viewer.event:constrain
      */
     applyConstraints: function( immediately ) {
         var actualZoom = this.getZoom(),
@@ -367,6 +394,16 @@ $.Viewport.prototype = {
         }
 
         if( this.viewer ){
+            /**
+             * Raised when the viewport constraints are applied (see {@link OpenSeadragon.Viewport#applyConstraints}).
+             *
+             * @event constrain
+             * @memberof OpenSeadragon.Viewer
+             * @type {object}
+             * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event.
+             * @property {Boolean} immediately
+             * @property {?Object} userData - Arbitrary subscriber-defined object.
+             */
             this.viewer.raiseEvent( 'constrain', {
                 immediately: immediately
             });
@@ -492,6 +529,7 @@ $.Viewport.prototype = {
      * @param {OpenSeadragon.Point} delta
      * @param {Boolean} immediately
      * @return {OpenSeadragon.Viewport} Chainable.
+     * @fires OpenSeadragon.Viewer.event:pan
      */
     panBy: function( delta, immediately ) {
         var center = new $.Point(
@@ -507,6 +545,7 @@ $.Viewport.prototype = {
      * @param {OpenSeadragon.Point} center
      * @param {Boolean} immediately
      * @return {OpenSeadragon.Viewport} Chainable.
+     * @fires OpenSeadragon.Viewer.event:pan
      */
     panTo: function( center, immediately ) {
         if ( immediately ) {
@@ -518,6 +557,17 @@ $.Viewport.prototype = {
         }
 
         if( this.viewer ){
+            /**
+             * Raised when the viewport is panned (see {@link OpenSeadragon.Viewport#panBy} and {@link OpenSeadragon.Viewport#panTo}).
+             *
+             * @event pan
+             * @memberof OpenSeadragon.Viewer
+             * @type {object}
+             * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event.
+             * @property {OpenSeadragon.Point} center
+             * @property {Boolean} immediately
+             * @property {?Object} userData - Arbitrary subscriber-defined object.
+             */
             this.viewer.raiseEvent( 'pan', {
                 center: center,
                 immediately: immediately
@@ -530,6 +580,7 @@ $.Viewport.prototype = {
     /**
      * @function
      * @return {OpenSeadragon.Viewport} Chainable.
+     * @fires OpenSeadragon.Viewer.event:zoom
      */
     zoomBy: function( factor, refPoint, immediately ) {
         if( refPoint instanceof $.Point && !isNaN( refPoint.x ) && !isNaN( refPoint.y ) ) {
@@ -544,6 +595,7 @@ $.Viewport.prototype = {
     /**
      * @function
      * @return {OpenSeadragon.Viewport} Chainable.
+     * @fires OpenSeadragon.Viewer.event:zoom
      */
     zoomTo: function( zoom, refPoint, immediately ) {
 
@@ -560,6 +612,18 @@ $.Viewport.prototype = {
         }
 
         if( this.viewer ){
+            /**
+             * Raised when the viewport zoom level changes (see {@link OpenSeadragon.Viewport#zoomBy} and {@link OpenSeadragon.Viewport#zoomTo}).
+             *
+             * @event zoom
+             * @memberof OpenSeadragon.Viewer
+             * @type {object}
+             * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event.
+             * @property {Number} zoom
+             * @property {OpenSeadragon.Point} refPoint
+             * @property {Boolean} immediately
+             * @property {?Object} userData - Arbitrary subscriber-defined object.
+             */
             this.viewer.raiseEvent( 'zoom', {
                 zoom: zoom,
                 refPoint: refPoint,
@@ -576,7 +640,6 @@ $.Viewport.prototype = {
      * debug mode doesn't rotate yet, and overlay rotation is only
      * partially supported.
      * @function
-     * @name OpenSeadragon.Viewport.prototype.setRotation
      * @return {OpenSeadragon.Viewport} Chainable.
      */
     setRotation: function( degrees ) {
@@ -597,7 +660,6 @@ $.Viewport.prototype = {
     /**
      * Gets the current rotation in degrees.
      * @function
-     * @name OpenSeadragon.Viewport.prototype.getRotation
      * @return {Number} The current rotation in degrees.
      */
     getRotation: function() {
@@ -607,6 +669,7 @@ $.Viewport.prototype = {
     /**
      * @function
      * @return {OpenSeadragon.Viewport} Chainable.
+     * @fires OpenSeadragon.Viewer.event:resize
      */
     resize: function( newContainerSize, maintain ) {
         var oldBounds = this.getBounds(),
@@ -625,6 +688,17 @@ $.Viewport.prototype = {
         }
 
         if( this.viewer ){
+            /**
+             * Raised when the viewer is resized (see {@link OpenSeadragon.Viewport#resize}).
+             *
+             * @event resize
+             * @memberof OpenSeadragon.Viewer
+             * @type {object}
+             * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised this event.
+             * @property {OpenSeadragon.Point} newContainerSize
+             * @property {Boolean} maintain
+             * @property {?Object} userData - Arbitrary subscriber-defined object.
+             */
             this.viewer.raiseEvent( 'resize', {
                 newContainerSize: newContainerSize,
                 maintain: maintain