Updated doclets

Creation options now documented in a typedef doclet named
OpenSeadragon.Options.

src/openseadragon.js

@@ -105,20 +105,16 @@
   */
 
  /**
-  * This function serves as a single point of instantiation for an {@link OpenSeadragon.Viewer}, including all
+  * All required and optional settings for instantiating a new instance of an OpenSeadragon image viewer.
-  * combinations of out-of-the-box configurable features.
   *
-  * @function OpenSeadragon
+  * @typedef {Object} Options
-  * @memberof module:OpenSeadragon
+  * @memberof OpenSeadragon
   *
-  * @param {Object} options All required and optional settings for instantiating
+  * @property {String} [xmlPath=null]
-  *     a new instance of an OpenSeadragon image viewer.
-  *
-  * @param {String} [options.xmlPath=null]
   *     DEPRECATED. A relative path to load a DZI file from the server.
-  *     Prefer the newer options.tileSources.
+  *     Prefer the newer Options.tileSources.
   *
-  * @param {Array|String|Function|Object[]|Array[]|String[]|Function[]} [options.tileSources=null]
+  * @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,
   *     the tileSource is used to create a {@link OpenSeadragon.DziTileSource}.
@@ -128,177 +124,177 @@
   *     is an Array of objects, it is used to create a
   *     {@link OpenSeadragon.LegacyTileSource}.
   *
-  * @param {Object} [options.tileHost=null]
+  * @property {Object} [tileHost=null]
   *     TODO: Implement this. Currently not used.
   *
-  * @param {Boolean} [options.debugMode=false]
+  * @property {Boolean} [debugMode=false]
   *     TODO: provide an in-screen panel providing event detail feedback.
   *
-  * @param {String} [options.debugGridColor='#437AB2']
+  * @property {String} [debugGridColor='#437AB2']
   *
-  * @param {Number} [options.animationTime=1.2]
+  * @property {Number} [animationTime=1.2]
   *     Specifies the animation duration per each {@link OpenSeadragon.Spring}
   *     which occur when the image is dragged or zoomed.
   *
-  * @param {Number} [options.blendTime=0]
+  * @property {Number} [blendTime=0]
   *     Specifies the duration of animation as higher or lower level tiles are
   *     replacing the existing tile.
   *
-  * @param {Boolean} [options.alwaysBlend=false]
+  * @property {Boolean} [alwaysBlend=false]
   *     Forces the tile to always blend.  By default the tiles skip blending
   *     when the blendTime is surpassed and the current animation frame would
   *     not complete the blend.
   *
-  * @param {Boolean} [options.autoHideControls=true]
+  * @property {Boolean} [autoHideControls=true]
   *     If the user stops interacting with the viewport, fade the navigation
   *     controls.  Useful for presentation since the controls are by default
   *     floated on top of the image the user is viewing.
   *
-  * @param {Boolean} [options.immediateRender=false]
+  * @property {Boolean} [immediateRender=false]
   *     Render the best closest level first, ignoring the lowering levels which
   *     provide the effect of very blurry to sharp. It is recommended to change
   *     setting to true for mobile devices.
   *
-  * @param {Number} [options.defaultZoomLevel=0]
+  * @property {Number} [defaultZoomLevel=0]
   *     Zoom level to use when image is first opened or the home button is clicked.
   *     If 0, adjusts to fit viewer.
   *
-  * @param {Number} [options.degrees=0]
+  * @property {Number} [degrees=0]
   *     Initial rotation.
   *
-  * @param {Number} [options.minZoomLevel=null]
+  * @property {Number} [minZoomLevel=null]
   *
-  * @param {Number} [options.maxZoomLevel=null]
+  * @property {Number} [maxZoomLevel=null]
   *
-  * @param {Boolean} [options.panHorizontal=true]
+  * @property {Boolean} [panHorizontal=true]
   *     Allow horizontal pan.
   *
-  * @param {Boolean} [options.panVertical=true]
+  * @property {Boolean} [panVertical=true]
   *     Allow vertical pan.
   *
-  * @param {Boolean} [options.constrainDuringPan=false]
+  * @property {Boolean} [constrainDuringPan=false]
   *
-  * @param {Boolean} [options.wrapHorizontal=false]
+  * @property {Boolean} [wrapHorizontal=false]
   *     Set to true to force the image to wrap horizontally within the viewport.
   *     Useful for maps or images representing the surface of a sphere or cylinder.
   *
-  * @param {Boolean} [options.wrapVertical=false]
+  * @property {Boolean} [wrapVertical=false]
   *     Set to true to force the image to wrap vertically within the viewport.
   *     Useful for maps or images representing the surface of a sphere or cylinder.
   *
-  * @param {Number} [options.minZoomImageRatio=0.9]
+  * @property {Number} [minZoomImageRatio=0.9]
   *     The minimum percentage ( expressed as a number between 0 and 1 ) of
   *     the viewport height or width at which the zoom out will be constrained.
   *     Setting it to 0, for example will allow you to zoom out infinitly.
   *
-  * @param {Number} [options.maxZoomPixelRatio=1.1]
+  * @property {Number} [maxZoomPixelRatio=1.1]
   *     The maximum ratio to allow a zoom-in to affect the highest level pixel
   *     ratio. This can be set to Infinity to allow 'infinite' zooming into the
   *     image though it is less effective visually if the HTML5 Canvas is not
   *     availble on the viewing device.
   *
-  * @param {Number} [options.pixelsPerWheelLine=40]
+  * @property {Number} [pixelsPerWheelLine=40]
   *     For pixel-resolution scrolling devices, the number of pixels equal to one scroll line.
   *
-  * @param {Number} [options.visibilityRatio=0.5]
+  * @property {Number} [visibilityRatio=0.5]
   *     The percentage ( as a number from 0 to 1 ) of the source image which
   *     must be kept within the viewport.  If the image is dragged beyond that
   *     limit, it will 'bounce' back until the minimum visibility ration is
   *     achieved.  Setting this to 0 and wrapHorizontal ( or wrapVertical ) to
   *     true will provide the effect of an infinitely scrolling viewport.
   *
-  * @param {Number} [options.springStiffness=7.0]
+  * @property {Number} [springStiffness=7.0]
   *
-  * @param {Number} [options.imageLoaderLimit=0]
+  * @property {Number} [imageLoaderLimit=0]
   *     The maximum number of image requests to make concurrently.  By default
   *     it is set to 0 allowing the browser to make the maximum number of
   *     image requests in parallel as allowed by the browsers policy.
   *
-  * @param {Number} [options.clickTimeThreshold=300]
+  * @property {Number} [clickTimeThreshold=300]
   *     If multiple mouse clicks occurs within less than this number of
   *     milliseconds, treat them as a single click.
   *
-  * @param {Number} [options.clickDistThreshold=5]
+  * @property {Number} [clickDistThreshold=5]
   *     If a mouse or touch drag occurs and the distance to the starting drag
   *     point is less than this many pixels, ignore the drag event.
   *
-  * @param {Number} [options.zoomPerClick=2.0]
+  * @property {Number} [zoomPerClick=2.0]
   *     The "zoom distance" per mouse click or touch tap.
   *
-  * @param {Number} [options.zoomPerScroll=1.2]
+  * @property {Number} [zoomPerScroll=1.2]
   *     The "zoom distance" per mouse scroll or touch pinch.
   *
-  * @param {Number} [options.zoomPerSecond=1.0]
+  * @property {Number} [zoomPerSecond=1.0]
   *     The number of seconds to animate a single zoom event over.
   *
-  * @param {Boolean} [options.showNavigationControl=true]
+  * @property {Boolean} [showNavigationControl=true]
   *     Set to false to prevent the appearance of the default navigation controls.
   *
-  * @param {Boolean} [options.showNavigator=false]
+  * @property {Boolean} [showNavigator=false]
   *     Set to true to make the navigator minimap appear.
   *
-  * @param {Boolean} [options.navigatorId=navigator-GENERATED DATE]
+  * @property {Boolean} [navigatorId=navigator-GENERATED DATE]
   *     Set the ID of a div to hold the navigator minimap.  If one is not specified,
   *     one will be generated and placed on top of the main image
   *
-  * @param {Number} [options.navigatorHeight=null]
+  * @property {Number} [navigatorHeight=null]
   *     TODO: Implement this. Currently not used.
   *
-  * @param {Number} [options.navigatorWidth=null]
+  * @property {Number} [navigatorWidth=null]
   *     TODO: Implement this. Currently not used.
   *
-  * @param {Number} [options.navigatorPosition=null]
+  * @property {Number} [navigatorPosition=null]
   *     TODO: Implement this. Currently not used.
   *
-  * @param {Number} [options.navigatorSizeRatio=0.2]
+  * @property {Number} [navigatorSizeRatio=0.2]
   *     Ratio of navigator size to viewer size.
   *
-  * @param {Number} [options.controlsFadeDelay=2000]
+  * @property {Number} [controlsFadeDelay=2000]
   *     The number of milliseconds to wait once the user has stopped interacting
   *     with the interface before begining to fade the controls. Assumes
   *     showNavigationControl and autoHideControls are both true.
   *
-  * @param {Number} [options.controlsFadeLength=1500]
+  * @property {Number} [controlsFadeLength=1500]
   *     The number of milliseconds to animate the controls fading out.
   *
-  * @param {Number} [options.maxImageCacheCount=200]
+  * @property {Number} [maxImageCacheCount=200]
   *     The max number of images we should keep in memory (per drawer).
   *
-  * @param {Number} [options.timeout=30000]
+  * @property {Number} [timeout=30000]
   *
-  * @param {Boolean} [options.useCanvas=true]
+  * @property {Boolean} [useCanvas=true]
   *     Set to false to not use an HTML canvas element for image rendering even if canvas is supported.
   *
-  * @param {Number} [options.minPixelRatio=0.5]
+  * @property {Number} [minPixelRatio=0.5]
   *     The higher the minPixelRatio, the lower the quality of the image that
   *     is considered sufficient to stop rendering a given zoom level.  For
   *     example, if you are targeting mobile devices with less bandwith you may
   *     try setting this to 1.5 or higher.
   *
-  * @param {Boolean} [options.mouseNavEnabled=true]
+  * @property {Boolean} [mouseNavEnabled=true]
   *     Is the user able to interact with the image via mouse or touch. Default
   *     interactions include draging the image in a plane, and zooming in toward
   *     and away from the image.
   *
-  * @param {Boolean} [options.showSequenceControl=true]
+  * @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.
   *
-  * @param {Number} [options.initialPage=0]
+  * @property {Number} [initialPage=0]
   *     If the viewer has been configured with a sequence of tile sources, display this page initially.
   *
-  * @param {Boolean} [options.preserveViewport=false]
+  * @property {Boolean} [preserveViewport=false]
   *     If the viewer has been configured with a sequence of tile sources, then
   *     normally navigating to through each image resets the viewport to 'home'
   *     position.  If preserveViewport is set to true, then the viewport position
   *     is preserved when navigating between images in the sequence.
   *
-  * @param {String} [options.prefixUrl='/images/']
+  * @property {String} [prefixUrl='/images/']
   *     Prepends the prefixUrl to navImages paths, which is very useful
   *     since the default paths are rarely useful for production
   *     environments.
   *
-  * @param {Object} [options.navImages=]
+  * @property {Object} [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
@@ -308,11 +304,20 @@
   *     these paths, prefer setting the option.prefixUrl rather than overriding
   *     every image path directly through this setting.
   *
-  * @param {Boolean} [options.navPrevNextWrap=false]
+  * @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.
   *
+  */
+
+ /**
+  * 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
   * @returns {OpenSeadragon.Viewer}
   */
 window.OpenSeadragon = window.OpenSeadragon || function( options ){

src/viewer.js

@@ -54,7 +54,7 @@ var THIS = {},
  * @memberof OpenSeadragon
  * @extends OpenSeadragon.EventSource
  * @extends OpenSeadragon.ControlDock
- * @param {Object} options
+ * @param {OpenSeadragon.Options} options
  * @param {String} options.element Id of Element to attach to,
  * @param {String} options.xmlPath  Xpath ( TODO: not sure! ),
  * @param {String} options.prefixUrl  Url used to prepend to paths, eg button