Updated Doclets

Lots of changes, most notably event documentation (@event and @fires)

src/button.js

@@ -35,10 +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,

src/drawer.js

@@ -171,6 +171,7 @@ $.Drawer.prototype = /** @lends OpenSeadragon.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;
@@ -201,11 +202,13 @@ $.Drawer.prototype = /** @lends OpenSeadragon.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
+             * @property {Element} element - The overlay element.
              * @property {OpenSeadragon.Point|OpenSeadragon.Rect} location
              * @property {OpenSeadragon.OverlayPlacement} placement
              * @property {?Object} userData - Arbitrary subscriber-defined object.
@@ -229,6 +232,7 @@ $.Drawer.prototype = /** @lends OpenSeadragon.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;
@@ -242,6 +246,8 @@ $.Drawer.prototype = /** @lends OpenSeadragon.Drawer.prototype */{
         }
         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}
@@ -267,6 +273,7 @@ $.Drawer.prototype = /** @lends OpenSeadragon.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;
@@ -281,11 +288,13 @@ $.Drawer.prototype = /** @lends OpenSeadragon.Drawer.prototype */{
         }
         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
+             * @property {Element} element - The overlay element.
              * @property {?Object} userData - Arbitrary subscriber-defined object.
              */
             this.viewer.raiseEvent( 'remove-overlay', {
@@ -300,6 +309,7 @@ $.Drawer.prototype = /** @lends OpenSeadragon.Drawer.prototype */{
      *      and update.
      * @method
      * @return {OpenSeadragon.Drawer} Chainable.
+     * @fires OpenSeadragon.Viewer.event:clear-overlay
      */
     clearOverlays: function() {
         while ( this.overlays.length > 0 ) {
@@ -308,6 +318,8 @@ $.Drawer.prototype = /** @lends OpenSeadragon.Drawer.prototype */{
         }
         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}
@@ -508,6 +520,8 @@ function updateViewport( drawer ) {
 
     if( drawer.viewer ){
         /**
+         * <em>- Needs documentation -</em>
+         *
          * @event update-viewport
          * @memberof OpenSeadragon.Viewer
          * @type {object}
@@ -689,6 +703,8 @@ function updateLevel( drawer, haveDrawn, drawLevel, level, levelOpacity, levelVi
 
     if( drawer.viewer ){
         /**
+         * <em>- Needs documentation -</em>
+         *
          * @event update-level
          * @memberof OpenSeadragon.Viewer
          * @type {object}
@@ -767,11 +783,13 @@ function updateTile( drawer, drawLevel, haveDrawn, x, y, level, levelOpacity, le
 
     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 {Object} tile
+         * @property {OpenSeadragon.Tile} tile
          * @property {?Object} userData - Arbitrary subscriber-defined object.
          */
         drawer.viewer.raiseEvent( 'update-tile', {
@@ -1289,11 +1307,13 @@ 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 {Object} tile
+             * @property {OpenSeadragon.Tile} tile
              * @property {?Object} userData - Arbitrary subscriber-defined object.
              */
             drawer.viewer.raiseEvent( 'tile-drawn', {

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/openseadragon.js

@@ -86,12 +86,13 @@
  * @version  <%= pkg.name %> <%= pkg.version %>
  *
  * @file
- * **OpenSeadragon - Javascript Deep Zooming**
+ * <h2><strong>OpenSeadragon - Javascript Deep Zooming</strong></h2>
- *
+ * <p>
- * OpenSeadragon is provides an html interface for creating
+ * 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>
  *
  */
 
@@ -128,7 +129,7 @@
   *     {@link OpenSeadragon.LegacyTileSource}.
   *
   * @property {String} [xmlPath=null]
-  *     **DEPRECATED**. A relative path to load a DZI file from the server.
+  *     <strong>DEPRECATED</strong>. A relative path to load a DZI file from the server.
   *     Prefer the newer Options.tileSources.
   *
   * @property {String} [prefixUrl='/images/']
@@ -241,10 +242,10 @@
   *     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. **Note:** Setting this to 1.0 effectively disables the click-to-zoom feature.
+  *     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. **Note:** Setting this to 1.0 effectively disables the mouse-wheel zoom feature.
+  *     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.
@@ -763,7 +764,7 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
 
 
         /**
-         * Invokes the the method as if it where a method belonging to the object.
+         * Invokes the method as if it where a method belonging to the object.
          * @function
          * @param {Object} object
          * @param {Function} method
@@ -780,9 +781,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.
          * @static
+         * @type {Object}
+         * @property {Number} UNKNOWN
+         * @property {Number} IE
+         * @property {Number} FIREFOX
+         * @property {Number} SAFARI
+         * @property {Number} CHROME
+         * @property {Number} OPERA
          */
         BROWSERS: {
             UNKNOWN:    0,
@@ -919,6 +926,7 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
          * @function
          * @param {Event} [event]
          * @returns {Event}
+         * @deprecated For internal use only
          */
         getEvent: function( event ) {
             if( event ){
@@ -1647,7 +1655,7 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
         /**
          * Fully deprecated. Will throw an error.
          * @function
-         * @deprecated - use OpenSeadragon.Viewer.prototype.open
+         * @deprecated use {@link OpenSeadragon.Viewer#open}
          */
         createFromDZI: function() {
             throw "OpenSeadragon.createFromDZI is deprecated, use Viewer.open.";

src/overlay.js

@@ -35,12 +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,
-     * RIGHT, BOTTOM_RIGHT, BOTTOM, BOTTOM_LEFT, and LEFT.
      * @member OverlayPlacement
      * @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,

src/tilesource.js

@@ -299,6 +299,8 @@ $.TileSource.prototype = /** @lends OpenSeadragon.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}
@@ -315,6 +317,8 @@ $.TileSource.prototype = /** @lends OpenSeadragon.TileSource.prototype */{
             readySource = new $TileSource( options );
             _this.ready = true;
             /**
+             * Raised when a TileSource is opened and initialized.
+             *
              * @event ready
              * @memberof OpenSeadragon.TileSource
              * @type {object}
@@ -363,6 +367,8 @@ $.TileSource.prototype = /** @lends OpenSeadragon.TileSource.prototype */{
                 }
 
                 /***
+                 * Raised when an error occurs loading a TileSource.
+                 *
                  * @event open-failed
                  * @memberof OpenSeadragon.TileSource
                  * @type {object}

src/viewer.js

@@ -406,7 +406,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
      * @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 );
@@ -420,7 +420,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
      * @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 );
@@ -445,6 +445,8 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
      * @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,
@@ -473,6 +475,8 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
                 });
                 tileSource.addHandler( 'open-failed', function ( event ) {
                     /**
+                     * Raised when an error occurs loading a TileSource.
+                     *
                      * @event open-failed
                      * @memberof OpenSeadragon.Viewer
                      * @type {object}
@@ -495,6 +499,8 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
                     $TileSource = $.TileSource.determineType( _this, tileSource );
                     if ( !$TileSource ) {
                         /***
+                         * Raised when an error occurs loading a TileSource.
+                         *
                          * @event open-failed
                          * @memberof OpenSeadragon.Viewer
                          * @type {object}
@@ -527,6 +533,7 @@ $.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 ) {
@@ -555,6 +562,8 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
         delete VIEWERS[ this.hash ];
 
         /**
+         * Raised when the viewer is closed (see {@link OpenSeadragon.Viewer#close}).
+         *
          * @event close
          * @memberof OpenSeadragon.Viewer
          * @type {object}
@@ -622,10 +631,13 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
      * @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}
@@ -660,6 +672,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
      * @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 ){
@@ -668,6 +681,8 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
             beginControlsAutoHide( this );
         }
         /**
+         * Raised when the navigation controls are shown or hidden (see {@link OpenSeadragon.Viewer#setControlsEnabled}).
+         *
          * @event controls-enabled
          * @memberof OpenSeadragon.Viewer
          * @type {object}
@@ -697,6 +712,8 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
      * @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 ) {
 
@@ -718,6 +735,8 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
             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}
@@ -872,6 +891,8 @@ $.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}
@@ -891,6 +912,8 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
      * @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;
@@ -908,6 +931,8 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
             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}
@@ -948,6 +973,8 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
                     }
                 }
                 /**
+                 * Raised when the viewer has changed to/from full-screen mode (see {@link OpenSeadragon.Viewer#setFullScreen}).
+                 *
                  * @event full-screen
                  * @memberof OpenSeadragon.Viewer
                  * @type {object}
@@ -983,10 +1010,13 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
      * @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}
@@ -1221,11 +1251,12 @@ $.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
@@ -1497,6 +1528,8 @@ 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}
@@ -1610,6 +1643,8 @@ function onCanvasClick( event ) {
         this.viewport.applyConstraints();
     }
     /**
+     * Raised when a mouse press/release or touch/remove occurs on the viewer.
+     *
      * @event canvas-click
      * @memberof OpenSeadragon.Viewer
      * @type {object}
@@ -1648,6 +1683,8 @@ function onCanvasDrag( event ) {
         }
     }
     /**
+     * Raised when a mouse or touch drag operation occurs in the viewer.
+     *
      * @event canvas-drag
      * @memberof OpenSeadragon.Viewer
      * @type {object}
@@ -1673,6 +1710,8 @@ function onCanvasRelease( event ) {
         this.viewport.applyConstraints();
     }
     /**
+     * Raised when the mouse button is released or touch ends in the viewer.
+     *
      * @event canvas-release
      * @memberof OpenSeadragon.Viewer
      * @type {object}
@@ -1704,6 +1743,8 @@ function onCanvasScroll( event ) {
         this.viewport.applyConstraints();
     }
     /**
+     * Raised when a scroll event occurs in the viewer (mouse wheel, touch pinch, etc.).
+     *
      * @event canvas-scroll
      * @memberof OpenSeadragon.Viewer
      * @type {object}
@@ -1734,6 +1775,8 @@ function onContainerExit( event ) {
         }
     }
     /**
+     * Raised when the cursor leaves the viewer element.
+     *
      * @event container-exit
      * @memberof OpenSeadragon.Viewer
      * @type {object}
@@ -1762,6 +1805,8 @@ function onContainerRelease( event ) {
         }
     }
     /**
+     * Raised when the mouse button is released or touch ends in the viewer.
+     *
      * @event container-release
      * @memberof OpenSeadragon.Viewer
      * @type {object}
@@ -1786,6 +1831,8 @@ function onContainerEnter( event ) {
     THIS[ this.hash ].mouseInside = true;
     abortControlsAutoHide( this );
     /**
+     * Raised when the cursor enters the viewer element.
+     *
      * @event container-enter
      * @memberof OpenSeadragon.Viewer
      * @type {object}
@@ -1854,6 +1901,8 @@ 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}
@@ -1870,6 +1919,8 @@ function updateOnce( viewer ) {
             viewer.navigator.update( viewer.viewport );
         }
         /**
+         * Raised when any spring animation update occurs (zoom, pan, etc.).
+         *
          * @event animation
          * @memberof OpenSeadragon.Viewer
          * @type {object}
@@ -1887,6 +1938,8 @@ 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}

src/viewport.js

@@ -111,6 +111,7 @@ $.Viewport.prototype = /** @lends OpenSeadragon.Viewport.prototype */{
     /**
      * @function
      * @return {OpenSeadragon.Viewport} Chainable.
+     * @fires OpenSeadragon.Viewer.event:reset-size
      */
     resetContentSize: function( contentSize ){
         this.contentSize    = contentSize;
@@ -123,6 +124,8 @@ $.Viewport.prototype = /** @lends OpenSeadragon.Viewport.prototype */{
 
         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}
@@ -173,10 +176,13 @@ $.Viewport.prototype = /** @lends OpenSeadragon.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}
@@ -314,6 +320,7 @@ $.Viewport.prototype = /** @lends OpenSeadragon.Viewport.prototype */{
     /**
      * @function
      * @return {OpenSeadragon.Viewport} Chainable.
+     * @fires OpenSeadragon.Viewer.event:constrain
      */
     applyConstraints: function( immediately ) {
         var actualZoom = this.getZoom(),
@@ -385,6 +392,8 @@ $.Viewport.prototype = /** @lends OpenSeadragon.Viewport.prototype */{
 
         if( this.viewer ){
             /**
+             * Raised when the viewport constraints are applied (see {@link OpenSeadragon.Viewport#applyConstraints}).
+             *
              * @event constrain
              * @memberof OpenSeadragon.Viewer
              * @type {object}
@@ -532,6 +541,7 @@ $.Viewport.prototype = /** @lends OpenSeadragon.Viewport.prototype */{
      * @param {OpenSeadragon.Point} center
      * @param {Boolean} immediately
      * @return {OpenSeadragon.Viewport} Chainable.
+     * @fires OpenSeadragon.Viewer.event:pan
      */
     panTo: function( center, immediately ) {
         if ( immediately ) {
@@ -544,6 +554,8 @@ $.Viewport.prototype = /** @lends OpenSeadragon.Viewport.prototype */{
 
         if( this.viewer ){
             /**
+             * Raised when the viewport is panned (see {@link OpenSeadragon.Viewport#panTo}).
+             *
              * @event pan
              * @memberof OpenSeadragon.Viewer
              * @type {object}
@@ -564,6 +576,7 @@ $.Viewport.prototype = /** @lends OpenSeadragon.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 ) ) {
@@ -578,6 +591,7 @@ $.Viewport.prototype = /** @lends OpenSeadragon.Viewport.prototype */{
     /**
      * @function
      * @return {OpenSeadragon.Viewport} Chainable.
+     * @fires OpenSeadragon.Viewer.event:zoom
      */
     zoomTo: function( zoom, refPoint, immediately ) {
 
@@ -595,6 +609,8 @@ $.Viewport.prototype = /** @lends OpenSeadragon.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}
@@ -649,6 +665,7 @@ $.Viewport.prototype = /** @lends OpenSeadragon.Viewport.prototype */{
     /**
      * @function
      * @return {OpenSeadragon.Viewport} Chainable.
+     * @fires OpenSeadragon.Viewer.event:resize
      */
     resize: function( newContainerSize, maintain ) {
         var oldBounds = this.getBounds(),
@@ -667,6 +684,8 @@ $.Viewport.prototype = /** @lends OpenSeadragon.Viewport.prototype */{
 
         if( this.viewer ){
             /**
+             * Raised when the viewer is resized (see {@link OpenSeadragon.Viewport#resize}).
+             *
              * @event resize
              * @memberof OpenSeadragon.Viewer
              * @type {object}