Updated doclets

Remaining creation options - still need descriptions on some.
Started event descriptions.
Viewer constructor parameters fixed.

src/button.js

@@ -181,6 +181,8 @@ $.Button = function( options ) {
             if ( event.insideElementPressed ) {
                 inTo( _this, $.ButtonState.DOWN );
                 /**
+                 * Raised when the cursor enters the Button element.
+                 *
                  * @event enter
                  * @memberof OpenSeadragon.Button
                  * @type {object}
@@ -197,6 +199,8 @@ $.Button = function( options ) {
         focusHandler: function ( event ) {
             this.enterHandler( event );
             /**
+             * Raised when the Button element receives focus.
+             *
              * @event focus
              * @memberof OpenSeadragon.Button
              * @type {object}
@@ -211,6 +215,8 @@ $.Button = function( options ) {
             outTo( _this, $.ButtonState.GROUP );
             if ( event.insideElementPressed ) {
                 /**
+                 * Raised when the cursor leaves the Button element.
+                 *
                  * @event exit
                  * @memberof OpenSeadragon.Button
                  * @type {object}
@@ -225,6 +231,8 @@ $.Button = function( options ) {
         blurHandler: function ( event ) {
             this.exitHandler( event );
             /**
+             * Raised when the Button element loses focus.
+             *
              * @event blur
              * @memberof OpenSeadragon.Button
              * @type {object}
@@ -238,6 +246,8 @@ $.Button = function( options ) {
         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}
@@ -252,6 +262,8 @@ $.Button = function( options ) {
             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}
@@ -270,6 +282,8 @@ $.Button = function( options ) {
         clickHandler: function( event ) {
             if ( event.quick ) {
                 /**
+                 * Raised when a mouse button is pressed and released or touch is initiated end ended in the Button element within the time and distance threshold.
+                 *
                  * @event click
                  * @memberof OpenSeadragon.Button
                  * @type {object}
@@ -285,6 +299,8 @@ $.Button = function( options ) {
             //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 end ended in the Button element within the time and distance threshold.
+                 *
                  * @event click
                  * @memberof OpenSeadragon.Button
                  * @type {object}
@@ -294,6 +310,8 @@ $.Button = function( options ) {
                  */
                 _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}

src/eventsource.js

@@ -39,7 +39,7 @@
  *
  * @callback EventHandler
  * @memberof OpenSeadragon
- * @param {Object} event - See individual events for event properties passed.
+ * @param {Object} event - See individual events for event-specific properties.
  */
 
 

src/openseadragon.js

@@ -82,27 +82,34 @@
  */
 
 
+/**
+ * @version  <%= pkg.name %> <%= pkg.version %>
+ *
+ * @file
+ * **OpenSeadragon - Javascript Deep Zooming**
+ *
+ * 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.
+ *
+ */
 
- /**
+/**
-  * @version  <%= pkg.name %> <%= pkg.version %>
+ * @module OpenSeadragon
-  *
+ *
-  * @fileOverview
+ */
-  * <h2>
-  * <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>
-  */
 
- /**
+/**
-  * @module OpenSeadragon
+ * The root namespace for OpenSeadragon.  All utility methods
-  */
+ * and classes are defined on or below this namespace.
+ *
+ * @namespace OpenSeadragon
+ *
+ */
+
+
+// Typedefs
 
  /**
   * All required and optional settings for instantiating a new instance of an OpenSeadragon image viewer.
@@ -110,10 +117,6 @@
   * @typedef {Object} Options
   * @memberof OpenSeadragon
   *
-  * @property {String} [xmlPath=null]
-  *     DEPRECATED. A relative path to load a DZI file from the server.
-  *     Prefer the newer Options.tileSources.
-  *
   * @property {Array|String|Function|Object[]|Array[]|String[]|Function[]} [tileSources=null]
   *     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,
@@ -124,6 +127,25 @@
   *     is an Array of objects, it is used to create a
   *     {@link OpenSeadragon.LegacyTileSource}.
   *
+  * @property {String} [xmlPath=null]
+  *     **DEPRECATED**. A relative path to load a DZI file from the server.
+  *     Prefer the newer Options.tileSources.
+  *
+  * @property {String} [prefixUrl='/images/']
+  *     Prepends the prefixUrl to navImages paths, which is very useful
+  *     since the default paths are rarely useful for production
+  *     environments.
+  *
+  * @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
+  *     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.
+  *
   * @property {Object} [tileHost=null]
   *     TODO: Implement this. Currently not used.
   *
@@ -276,6 +298,11 @@
   *     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.
@@ -289,35 +316,84 @@
   *     position.  If preserveViewport is set to true, then the viewport position
   *     is preserved when navigating between images in the sequence.
   *
-  * @property {String} [prefixUrl='/images/']
+  * @property {Boolean} [showReferenceStrip=false]
-  *     Prepends the prefixUrl to navImages paths, which is very useful
+  *     If the viewer has been configured with a sequence of tile sources, then
-  *     since the default paths are rarely useful for production
+  *     display a scrolling strip of image thumbnails for navigating through the images.
-  *     environments.
   *
-  * @property {Object} [navImages=]
+  * @property {String} [referenceStripScroll='horizontal']
-  *     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
-  *     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.
   *
-  * @property {Boolean} [navPrevNextWrap=false]
+  * @property {Element} [referenceStripElement=null]
-  *     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
+  * @property {Number} [referenceStripHeight=null]
-  *     the last image.
+  *
+  * @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
+  * @param {OpenSeadragon.Options} options - Viewer options.
   * @returns {OpenSeadragon.Viewer}
   */
 window.OpenSeadragon = window.OpenSeadragon || function( options ){
@@ -327,14 +403,6 @@ window.OpenSeadragon = window.OpenSeadragon || function( options ){
 };
 
 
-/**
- * The root namespace for OpenSeadragon.  All utility methods
- * and classes are defined on or below this namespace.
- *
- * @namespace OpenSeadragon
- */
-
-
 (function( $ ){
 
 

src/viewer.js

@@ -54,17 +54,13 @@ var THIS = {},
  * @memberof OpenSeadragon
  * @extends OpenSeadragon.EventSource
  * @extends OpenSeadragon.ControlDock
- * @param {OpenSeadragon.Options} options
+ * @param {OpenSeadragon.Options} [options] - Viewer options. If an {@link OpenSeadragon.Options} object is passed first, all other parameters are ignored. This is the preferred method of creating a viewer.
- * @param {String} options.element Id of Element to attach to,
+ * @param {String} element - Id of Element to attach to,
- * @param {String} options.xmlPath  Xpath ( TODO: not sure! ),
+ * @param {String} xmlPath - Xpath ( TODO: not sure! ),
- * @param {String} options.prefixUrl  Url used to prepend to paths, eg button
+ * @param {String} prefixUrl - Url used to prepend to paths, eg button images, etc.
- *  images, etc.
+ * @param {OpenSeadragon.Control[]} controls - Array of OpenSeadragon.Control,
- * @param {OpenSeadragon.Control[]} options.controls Array of OpenSeadragon.Control,
+ * @param {OpenSeadragon.Overlay[]} overlays - Array of OpenSeadragon.Overlay,
- * @param {OpenSeadragon.Overlay[]} options.overlays Array of OpenSeadragon.Overlay,
+ * @param {OpenSeadragon.Control[]} overlayControls - An Array of ( TODO: not sure! )
- * @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 ) {
@@ -126,13 +122,26 @@ $.Viewer = function( options ) {
         //These are originally not part options but declared as members
         //in initialize.  Its still considered idiomatic to put them here
         source:         null,
+        /**
+         * @member {OpenSeadragon.Drawer} drawer
+         * @memberof OpenSeadragon.Viewer#
+         */
         drawer:         null,
         drawers:        [],
+        /**
+         * The viewer's viewport, where you can access zoom, pan, etc.
+         * @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
+        //simultanious rendering of sets of tiles
         collectionViewport:     null,
         collectionDrawer:       null,