Updated Doclets

src/button.js

@@ -53,39 +53,30 @@ $.ButtonState = {
 };
 
 /**
- * Manages events, hover states for individual buttons, tool-tips, as well
+ * @class Button
+ * @classdesc Manages events, hover states for individual buttons, tool-tips, as well
  * as fading the bottons out when the user has not interacted with them
  * for a specified period.
- * @class Button
+ *
  * @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 ) {
 
@@ -102,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,
@@ -116,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
@@ -167,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,

src/buttongroup.js

@@ -34,43 +34,41 @@
 
 (function( $ ){
 /**
- * Manages events on groups of buttons.
  * @class ButtonGroup
+ * @classdesc Manages events on groups of buttons.
+ *
  * @memberof OpenSeadragon
- * @param {Object} options - a dictionary of settings applied against the entire
+ * @param {Object} options - A dictionary of settings applied against the entire group of buttons.
- * group of buttons
  * @param {Array} options.buttons Array of buttons
- * @param {Element}  [options.group]   Element to use as the container,
+ * @param {Element} [options.element] Element to use as the container
- * @param {Object}   options.config  Object with Viewer settings ( TODO: is
- *  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
@@ -82,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,
@@ -117,6 +120,7 @@ $.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
+     * @private
      */
     emulateEnter: function() {
         this.tracker.enterHandler( { eventSource: this.tracker } );
@@ -126,6 +130,7 @@ $.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
+     * @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,11 @@ $.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 Control
+ *
  * @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.
@@ -62,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;
@@ -83,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 );

src/controldock.js

@@ -35,6 +35,8 @@
 (function( $ ){
     /**
      * @class ControlDock
+     * @classdesc Provides a container element (a <form> element) with support for the layout of control elements.
+     *
      * @memberof OpenSeadragon
      */
     $.ControlDock = function( options ){

src/displayrectangle.js

@@ -35,10 +35,11 @@
 (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 DisplayRect
+ *
  * @memberof OpenSeadragon
  * @extends OpenSeadragon.Rect
  * @param {Number} x The vector component 'x'.
@@ -47,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

@@ -49,27 +49,13 @@ var DEVICE_SCREEN       = $.getWindowSize(),
 
 /**
  * @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 ) {
 
@@ -80,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.
         };
     }
 
@@ -90,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
@@ -120,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.
@@ -447,6 +456,11 @@ $.Drawer.prototype = /** @lends OpenSeadragon.Drawer.prototype */{
         return loading;
     },
 
+    /**
+     * Returns whether rotation is supported or not.
+     * @method
+     * @return {Boolean} True if rotation is supported.
+     */
     canRotate: function() {
         return this.useCanvas;
     }

src/eventsource.js

@@ -44,10 +44,9 @@
 
 
 /**
- * For use by classes which want to support custom, non-browser events.
- * TODO: Add a method 'one' which automatically unbinds a listener after 
- *       the first triggered event that matches.
  * @class EventSource
+ * @classdesc For use by classes which want to support custom, non-browser events.
+ *
  * @memberof OpenSeadragon
  */
 $.EventSource = function() {
@@ -56,6 +55,8 @@ $.EventSource = function() {
 
 $.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

src/iiif1_1tilesource.js

@@ -35,10 +35,10 @@
 (function( $ ){
 
 /**
- * A client implementation of the International Image Interoperability
+ * @class IIIF1_1TileSource
+ * @classdesc A client implementation of the International Image Interoperability
  * Format: Image API 1.1
  *
- * @class IIIF1_1TileSource
  * @memberof OpenSeadragon
  * @extends OpenSeadragon.TileSource
  * @see http://library.stanford.edu/iiif/image-api/

src/iiiftilesource.js

@@ -42,10 +42,10 @@
 (function( $ ){
 
 /**
- * A client implementation of the International Image Interoperability
+ * @class IIIFTileSource
+ * @classdesc A client implementation of the International Image Interoperability
  * Format: Image API Draft 0.2
  *
- * @class IIIFTileSource
  * @memberof OpenSeadragon
  * @extends OpenSeadragon.TileSource
  * @see http://library.stanford.edu/iiif/image-api/

src/legacytilesource.js

@@ -35,13 +35,14 @@
 (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 LegacyTileSource
+ *
  * @memberof OpenSeadragon
  * @extends OpenSeadragon.TileSource
  * @param {Array} levels An array of file descriptions, each is an object with

src/mousetracker.js

@@ -46,18 +46,19 @@
         THIS           = {};
 
     /**
-     * The MouseTracker allows other classes to set handlers for common mouse
-     * events on a specific element like, 'enter', 'exit', 'press', 'release',
-     * 'scroll', 'click', and 'drag'.
      * @class MouseTracker
+     * @classdesc Provides simplified handling of common mouse, touch, and keyboard
+     * events on a specific element, like 'enter', 'exit', 'press', 'release',
+     * 'scroll', 'click', and 'drag'.
+     *
      * @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
@@ -65,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 {OpenSeadragon.EventHandler} options.enterHandler
+     * @param {OpenSeadragon.EventHandler} [options.enterHandler=null]
      *      An optional handler for mouse enter.
-     * @param {OpenSeadragon.EventHandler} options.exitHandler
+     * @param {OpenSeadragon.EventHandler} [options.exitHandler=null]
      *      An optional handler for mouse exit.
-     * @param {OpenSeadragon.EventHandler} options.pressHandler
+     * @param {OpenSeadragon.EventHandler} [options.pressHandler=null]
      *      An optional handler for mouse press.
-     * @param {OpenSeadragon.EventHandler} options.releaseHandler
+     * @param {OpenSeadragon.EventHandler} [options.releaseHandler=null]
      *      An optional handler for mouse release.
-     * @param {OpenSeadragon.EventHandler} options.moveHandler
+     * @param {OpenSeadragon.EventHandler} [options.moveHandler=null]
      *      An optional handler for mouse move.
-     * @param {OpenSeadragon.EventHandler} options.scrollHandler
+     * @param {OpenSeadragon.EventHandler} [options.scrollHandler=null]
      *      An optional handler for mouse scroll.
-     * @param {OpenSeadragon.EventHandler} options.clickHandler
+     * @param {OpenSeadragon.EventHandler} [options.clickHandler=null]
      *      An optional handler for mouse click.
-     * @param {OpenSeadragon.EventHandler} options.dragHandler
+     * @param {OpenSeadragon.EventHandler} [options.dragHandler=null]
      *      An optional handler for mouse drag.
-     * @param {OpenSeadragon.EventHandler} options.keyHandler
+     * @param {OpenSeadragon.EventHandler} [options.keyHandler=null]
      *      An optional handler for keypress.
-     * @param {OpenSeadragon.EventHandler} options.focusHandler
+     * @param {OpenSeadragon.EventHandler} [options.focusHandler=null]
      *      An optional handler for focus.
-     * @param {OpenSeadragon.EventHandler} 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 ) {
 
@@ -115,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;

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 Navigator
+ *
  * @memberof OpenSeadragon
  * @extends OpenSeadragon.Viewer
  * @extends OpenSeadragon.EventSource
  * @param {Object} options
- * @param {String} options.viewerId
  */
 $.Navigator = function( options ){
 

src/openseadragon.js

@@ -118,6 +118,14 @@
   * @typedef {Object} Options
   * @memberof OpenSeadragon
   *
+  * @property {String} id
+  *     Id of the element to append the viewer's container element to. If not provided, the 'element' 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.
+  *
+  * @property {Element} element
+  *     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.
+  *
   * @property {Array|String|Function|Object[]|Array[]|String[]|Function[]} [tileSources=null]
   *     As an Array, the tileSource can hold either Objects or mixed
   *     types of Arrays of Objects, Strings, or Functions. When a value is a String,
@@ -625,11 +633,9 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
 
     $.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}.
-         * at {@link OpenSeadragon.Options}.
-         * @member DEFAULT_SETTINGS
-         * @memberof OpenSeadragon
          * @static
+         * @type {Object}
          */
         DEFAULT_SETTINGS: {
             //DATA SOURCE DETAILS
@@ -764,10 +770,11 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
 
 
         /**
-         * Invokes 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.
          * @function
          * @param {Object} object
          * @param {Function} method
+         * @returns {Function}
          */
         delegate: function( object, method ) {
             return function(){
@@ -921,12 +928,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
          * @param {Event} [event]
          * @returns {Event}
          * @deprecated For internal use only
+         * @private
          */
         getEvent: function( event ) {
             if( event ){
@@ -1717,12 +1724,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 *'alpha'* - Does the browser support image alpha
-     *  transparency.<br/>
      * @member {Object} Browser
      * @memberof OpenSeadragon
      * @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,6 @@
  * pixel size. I.e. the Deep Zoom image dimension is 65.572.864x65.572.864
  * pixels.
  *
- * @class OsmTileSource
  * @memberof OpenSeadragon
  * @extends OpenSeadragon.TileSource
  * @param {Number|Object} width - the pixel width of the image or the idiomatic

src/overlay.js

@@ -63,12 +63,28 @@
     };
 
     /**
-     * An Overlay provides a
      * @class Overlay
+     * @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;

src/point.js

@@ -35,18 +35,27 @@
 (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 Point
+ *
  * @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;
 };
 

src/profiler.js

@@ -35,9 +35,10 @@
 (function( $ ){
 
 /**
- * A utility class useful for developers to establish baseline performance
- * metrics of rendering routines.
  * @class Profiler
+ * @classdesc A utility class useful for developers to establish baseline performance
+ * metrics of rendering routines.
+ *
  * @memberof OpenSeadragon
  * @property {Boolean} midUpdate
  * @property {Number} numUpdates

src/rectangle.js

@@ -35,26 +35,42 @@
 (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 Rect
  * @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;
 };
 

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

@@ -42,14 +42,6 @@
  *  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;
@@ -61,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
@@ -72,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 :
@@ -80,11 +87,23 @@ $.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

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

@@ -45,53 +45,130 @@
  * @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;
 };
 

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,7 @@
  * 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 TileSource
+ *
  * @memberof OpenSeadragon
  * @extends OpenSeadragon.EventSource
  * @param {Number|Object|Array|String} width
@@ -71,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,
@@ -126,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

src/tmstilesource.js

@@ -43,11 +43,11 @@
 (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 TmsTileSource
  * @memberof OpenSeadragon
  * @extends OpenSeadragon.TileSource
  * @param {Number|Object} width - the pixel width of the image or the idiomatic

src/viewer.js

@@ -51,6 +51,8 @@ var THIS = {},
  * as arguments and we translate a positional call into an idiomatic call.
  *
  * @class Viewer
+ * @classdesc The main OpenSeadragon viewer class.
+ *
  * @memberof OpenSeadragon
  * @extends OpenSeadragon.EventSource
  * @extends OpenSeadragon.ControlDock
@@ -94,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:       [],
@@ -117,13 +146,14 @@ $.Viewer = function( options ) {
         //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:        [],
         /**
-         * The viewer's viewport, where you can access zoom, pan, etc.
+         * Handles coordinate-related functionality - zoom, pan, rotation, etc. Created for each TileSource opened.
          * @member {OpenSeadragon.Viewport} viewport
          * @memberof OpenSeadragon.Viewer#
          */
@@ -416,7 +446,6 @@ $.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.
      *
@@ -442,7 +471,6 @@ $.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
@@ -531,7 +559,6 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
 
     /**
      * @function
-     * @name OpenSeadragon.Viewer.prototype.close
      * @return {OpenSeadragon.Viewer} Chainable.
      * @fires OpenSeadragon.Viewer.event:close
      */
@@ -580,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();
@@ -619,7 +645,6 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
 
     /**
      * @function
-     * @name OpenSeadragon.Viewer.prototype.isMouseNavEnabled
      * @return {Boolean}
      */
     isMouseNavEnabled: function () {
@@ -628,7 +653,6 @@ $.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
@@ -652,7 +676,6 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
 
     /**
      * @function
-     * @name OpenSeadragon.Viewer.prototype.areControlsEnabled
      * @return {Boolean}
      */
     areControlsEnabled: function () {
@@ -669,7 +692,6 @@ $.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
@@ -697,7 +719,6 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
 
     /**
      * @function
-     * @name OpenSeadragon.Viewer.prototype.isFullPage
      * @return {Boolean}
      */
     isFullPage: function () {
@@ -708,7 +729,6 @@ $.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.
@@ -908,7 +928,6 @@ $.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.
@@ -997,7 +1016,6 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
 
     /**
      * @function
-     * @name OpenSeadragon.Viewer.prototype.isVisible
      * @return {Boolean}
      */
     isVisible: function () {
@@ -1007,7 +1025,6 @@ $.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
@@ -1031,7 +1048,6 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
 
     /**
      * @function
-     * @name OpenSeadragon.Viewer.prototype.bindSequenceControls
      * @return {OpenSeadragon.Viewer} Chainable.
      */
     bindSequenceControls: function(){
@@ -1117,7 +1133,6 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
 
     /**
      * @function
-     * @name OpenSeadragon.Viewer.prototype.bindStandardControls
      * @return {OpenSeadragon.Viewer} Chainable.
      */
     bindStandardControls: function(){
@@ -1240,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 () {
@@ -1249,7 +1263,6 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
 
     /**
      * @function
-     * @name OpenSeadragon.Viewer.prototype.goToPage
      * @return {OpenSeadragon.Viewer} Chainable.
      * @fires OpenSeadragon.Viewer.event:page
      */
@@ -1643,7 +1656,7 @@ function onCanvasClick( event ) {
         this.viewport.applyConstraints();
     }
     /**
-     * Raised when a mouse press/release or touch/remove occurs on the viewer.
+     * Raised when a mouse press/release or touch/remove occurs on the {@link OpenSeadragon.Viewer#canvas} element.
      *
      * @event canvas-click
      * @memberof OpenSeadragon.Viewer
@@ -1683,7 +1696,7 @@ function onCanvasDrag( event ) {
         }
     }
     /**
-     * Raised when a mouse or touch drag operation occurs in the viewer.
+     * Raised when a mouse or touch drag operation occurs on the {@link OpenSeadragon.Viewer#canvas} element.
      *
      * @event canvas-drag
      * @memberof OpenSeadragon.Viewer
@@ -1710,7 +1723,7 @@ function onCanvasRelease( event ) {
         this.viewport.applyConstraints();
     }
     /**
-     * Raised when the mouse button is released or touch ends in the viewer.
+     * Raised when the mouse button is released or touch ends on the {@link OpenSeadragon.Viewer#canvas} element.
      *
      * @event canvas-release
      * @memberof OpenSeadragon.Viewer
@@ -1743,7 +1756,7 @@ function onCanvasScroll( event ) {
         this.viewport.applyConstraints();
     }
     /**
-     * Raised when a scroll event occurs in the viewer (mouse wheel, touch pinch, etc.).
+     * Raised when a scroll event occurs on the {@link OpenSeadragon.Viewer#canvas} element (mouse wheel, touch pinch, etc.).
      *
      * @event canvas-scroll
      * @memberof OpenSeadragon.Viewer
@@ -1775,7 +1788,7 @@ function onContainerExit( event ) {
         }
     }
     /**
-     * Raised when the cursor leaves the viewer element.
+     * Raised when the cursor leaves the {@link OpenSeadragon.Viewer#container} element.
      *
      * @event container-exit
      * @memberof OpenSeadragon.Viewer
@@ -1805,7 +1818,7 @@ function onContainerRelease( event ) {
         }
     }
     /**
-     * Raised when the mouse button is released or touch ends in the viewer.
+     * Raised when the mouse button is released or touch ends on the {@link OpenSeadragon.Viewer#container} element.
      *
      * @event container-release
      * @memberof OpenSeadragon.Viewer
@@ -1831,7 +1844,7 @@ function onContainerEnter( event ) {
     THIS[ this.hash ].mouseInside = true;
     abortControlsAutoHide( this );
     /**
-     * Raised when the cursor enters the viewer element.
+     * Raised when the cursor enters the {@link OpenSeadragon.Viewer#container} element.
      *
      * @event container-enter
      * @memberof OpenSeadragon.Viewer

src/viewport.js

@@ -37,6 +37,9 @@
 
 /**
  * @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 ) {