Merge branch 'openseadragon:master' into master

changelog.txt

@@ -9,10 +9,11 @@ OPENSEADRAGON CHANGELOG
 * You can now provide an element for the navigator (as an alternative to an ID) (#1303 @cameronbaney, #2166 #2175 @joedf)
 * Now supporting IIIF "id" and "identifier" in addition to "@id" (#2173 @ahankinson)
 * We now delegate tile fetching and caching to the TileSource, to allow for custom tile formats (#2148 @Aiosa)
+* Improved documentation (#2211 @shyamkumaryadav)
 * Fixed: Cropping tiled images with polygons was broken (#2183 @altert)
 * Fixed: Disabling buttons only changed their appearance, but they were still clickable (#2187 @pearcetm)
 * Fixed: ImageTileSource produced an error having to do with getTileHashKey (#2190 @Aiosa)
-* Fixed: On startup you would get an unnecessary "Viewer.buttons is deprecated" warning (#2201 @joedf)
+* Fixed: On startup you would get an unnecessary "Viewer.buttons is deprecated" warning (#2201 @joedf, #2219 @jssullivan, #2212 @joedf)
 
 3.1.0:
 

src/control.js

@@ -172,7 +172,7 @@ $.Control.prototype = {
     /**
      * Determines if the control is currently visible.
      * @function
-     * @return {Boolean} true if currently visible, false otherwise.
+     * @returns {Boolean} true if currently visible, false otherwise.
      */
     isVisible: function() {
         return this.wrapper.style.display !== "none";

src/controldock.js

@@ -149,7 +149,7 @@
 
         /**
          * @function
-         * @return {OpenSeadragon.ControlDock} Chainable.
+         * @returns {OpenSeadragon.ControlDock} Chainable.
          */
         removeControl: function ( element ) {
             element = $.getElement( element );
@@ -165,7 +165,7 @@
 
         /**
          * @function
-         * @return {OpenSeadragon.ControlDock} Chainable.
+         * @returns {OpenSeadragon.ControlDock} Chainable.
          */
         clearControls: function () {
             while ( this.controls.length > 0 ) {
@@ -178,7 +178,7 @@
 
         /**
          * @function
-         * @return {Boolean}
+         * @returns {Boolean}
          */
         areControlsEnabled: function () {
             var i;
@@ -195,7 +195,7 @@
 
         /**
          * @function
-         * @return {OpenSeadragon.ControlDock} Chainable.
+         * @returns {OpenSeadragon.ControlDock} Chainable.
          */
         setControlsEnabled: function( enabled ) {
             var i;

src/drawer.js

@@ -176,6 +176,7 @@ $.Drawer.prototype = {
      * This function does not take rotation into account, thus assuming provided
      * point is at 0 degree.
      * @param {OpenSeadragon.Point} point - the pixel point to convert
+     * @returns {OpenSeadragon.Point} Point in drawer coordinate system.
      */
     viewportCoordToDrawerCoord: function(point) {
         var vpPoint = this.viewport.pixelFromPointNoRotate(point, true);
@@ -208,7 +209,7 @@ $.Drawer.prototype = {
     /**
      * Set the opacity of the drawer.
      * @param {Number} opacity
-     * @return {OpenSeadragon.Drawer} Chainable.
+     * @returns {OpenSeadragon.Drawer} Chainable.
      */
     setOpacity: function( opacity ) {
         $.console.error("drawer.setOpacity is deprecated. Use tiledImage.setOpacity instead.");
@@ -264,7 +265,7 @@ $.Drawer.prototype = {
     },
 
     /**
-     * @return {Boolean} True if rotation is supported.
+     * @returns {Boolean} True if rotation is supported.
      */
     canRotate: function() {
         return this.useCanvas;
@@ -321,7 +322,7 @@ $.Drawer.prototype = {
      * Scale from OpenSeadragon viewer rectangle to drawer rectangle
      * (ignoring rotation)
      * @param {OpenSeadragon.Rect} rectangle - The rectangle in viewport coordinate system.
-     * @return {OpenSeadragon.Rect} Rectangle in drawer coordinate system.
+     * @returns {OpenSeadragon.Rect} Rectangle in drawer coordinate system.
      */
     viewportToDrawerRectangle: function(rectangle) {
         var topLeft = this.viewport.pixelFromPointNoRotate(rectangle.getTopLeft(), true);

src/dzitilesource.js

@@ -125,7 +125,7 @@ $.extend( $.DziTileSource.prototype, $.TileSource.prototype, /** @lends OpenSead
      * @param {Object|XMLDocument} data - the raw configuration
      * @param {String} url - the url the data was retrieved from if any.
      * @param {String} postData - HTTP POST data in k=v&k2=v2... form or null
-     * @return {Object} options - A dictionary of keyword arguments sufficient
+     * @returns {Object} options - A dictionary of keyword arguments sufficient
      *      to configure this tile sources constructor.
      */
     configure: function( data, url, postData ){

src/eventsource.js

@@ -125,7 +125,7 @@ $.EventSource.prototype = {
     /**
      * Get the amount of handlers registered for a given event.
      * @param {String} eventName - Name of event to inspect.
-     * @return {number} amount of events
+     * @returns {number} amount of events
      */
     numberOfHandlers: function (eventName) {
         var events = this.events[ eventName ];

src/iiiftilesource.js

@@ -193,7 +193,7 @@ $.extend( $.IIIFTileSource.prototype, $.TileSource.prototype, /** @lends OpenSea
      * @param {Object} data - the raw configuration
      * @param {String} url - the url configuration was retrieved from
      * @param {String} postData - HTTP POST data in k=v&k2=v2... form or null
-     * @return {Object} A normalized IIIF data object
+     * @returns {Object} A normalized IIIF data object
      * @example <caption>IIIF 2.x Info Looks like this</caption>
      * {
      * "@context": "http://iiif.io/api/image/2/context.json",
@@ -456,7 +456,7 @@ $.extend( $.IIIFTileSource.prototype, $.TileSource.prototype, /** @lends OpenSea
      * @param {Object} options
      * @param {Array|String} options.profile
      * @param {Number} options.version
-     * @param {String} options.extraFeatures
+     * @param {String[]} options.extraFeatures
      * @returns {Boolean}
      */
     function canBeTiled ( options ) {

src/imagetilesource.js

@@ -90,7 +90,7 @@
          * @param {Object} options - the options
          * @param {String} dataUrl - the url the image was retrieved from, if any.
          * @param {String} postData - HTTP POST data in k=v&k2=v2... form or null
-         * @return {Object} options - A dictionary of keyword arguments sufficient
+         * @returns {Object} options - A dictionary of keyword arguments sufficient
          *      to configure this tile sources constructor.
          */
         configure: function (options, dataUrl, postData) {

src/legacytilesource.js

@@ -123,7 +123,7 @@ $.extend( $.LegacyTileSource.prototype, $.TileSource.prototype, /** @lends OpenS
      * @param {Object|XMLDocument} configuration - the raw configuration
      * @param {String} dataUrl - the url the data was retrieved from if any.
      * @param {String} postData - HTTP POST data in k=v&k2=v2... form or null
-     * @return {Object} options - A dictionary of keyword arguments sufficient
+     * @returns {Object} options - A dictionary of keyword arguments sufficient
      *      to configure this tile sources constructor.
      */
     configure: function( configuration, dataUrl, postData ){

src/openseadragon.js

@@ -922,7 +922,7 @@ function OpenSeadragon( options ){
     /**
      * Shim around Object.freeze. Does nothing if Object.freeze is not supported.
      * @param {Object} obj The object to freeze.
-     * @return {Object} obj The frozen object.
+     * @returns {Object} obj The frozen object.
      */
     $.freezeObject = function(obj) {
         if (Object.freeze) {
@@ -1102,12 +1102,18 @@ function OpenSeadragon( options ){
                 // Extend the base object
                 for ( name in options ) {
                     var descriptor = Object.getOwnPropertyDescriptor(options, name);
+
+                    if (descriptor !== undefined) {
                         if (descriptor.get || descriptor.set) {
                             Object.defineProperty(target, name, descriptor);
                             continue;
                         }
 
                         copy = descriptor.value;
+                    } else {
+                        $.console.warn('Could not copy inherited property "' + name + '".');
+                        continue;
+                    }
 
                     // Prevent never-ending loop
                     if ( target === copy ) {
@@ -2110,7 +2116,7 @@ function OpenSeadragon( options ){
          * @param {Boolean} [options.capture]
          * @param {Boolean} [options.passive]
          * @param {Boolean} [options.once]
-         * @return {String} The protocol (http:, https:, file:, ftp: ...)
+         * @returns {String} The protocol (http:, https:, file:, ftp: ...)
          */
         normalizeEventListenerOptions: function (options) {
             var opts;
@@ -2274,7 +2280,7 @@ function OpenSeadragon( options ){
          * @function
          * @private
          * @param {String} url The url to retrieve the protocol from.
-         * @return {String} The protocol (http:, https:, file:, ftp: ...)
+         * @returns {String} The protocol (http:, https:, file:, ftp: ...)
          */
         getUrlProtocol: function( url ) {
             var match = url.match(/^([a-z]+:)\/\//i);

src/osmtilesource.js

@@ -123,7 +123,7 @@ $.extend( $.OsmTileSource.prototype, $.TileSource.prototype, /** @lends OpenSead
      * @param {Object} data - the raw configuration
      * @param {String} url - the url the data was retrieved from if any.
      * @param {String} postData - HTTP POST data in k=v&k2=v2... form or null
-     * @return {Object} options - A dictionary of keyword arguments sufficient
+     * @returns {Object} options - A dictionary of keyword arguments sufficient
      *      to configure this tile sources constructor.
      */
     configure: function( data, url, postData ){

src/rectangle.js

@@ -240,7 +240,7 @@ $.Rect.prototype = {
      * Determines if two Rectangles have equivalent components.
      * @function
      * @param {OpenSeadragon.Rect} rectangle The Rectangle to compare to.
-     * @return {Boolean} 'true' if all components are equal, otherwise 'false'.
+     * @returns {Boolean} 'true' if all components are equal, otherwise 'false'.
      */
     equals: function(other) {
         return (other instanceof $.Rect) &&
@@ -287,7 +287,7 @@ $.Rect.prototype = {
      * Returns the smallest rectangle that will contain this and the given
      * rectangle bounding boxes.
      * @param {OpenSeadragon.Rect} rect
-     * @return {OpenSeadragon.Rect} The new rectangle.
+     * @returns {OpenSeadragon.Rect} The new rectangle.
      */
     union: function(rect) {
         var thisBoundingBox = this.getBoundingBox();
@@ -313,7 +313,7 @@ $.Rect.prototype = {
      * Returns the bounding box of the intersection of this rectangle with the
      * given rectangle.
      * @param {OpenSeadragon.Rect} rect
-     * @return {OpenSeadragon.Rect} the bounding box of the intersection
+     * @returns {OpenSeadragon.Rect} the bounding box of the intersection
      * or null if the rectangles don't intersect.
      */
     intersection: function(rect) {
@@ -441,7 +441,7 @@ $.Rect.prototype = {
      * @param {Number} degrees The angle in degrees to rotate.
      * @param {OpenSeadragon.Point} [pivot] The point about which to rotate.
      * Defaults to the center of the rectangle.
-     * @return {OpenSeadragon.Rect}
+     * @returns {OpenSeadragon.Rect}
      */
     rotate: function(degrees, pivot) {
         degrees = $.positiveModulo(degrees, 360);

src/tile.js

@@ -335,7 +335,7 @@ $.Tile.prototype = {
      * @member {Object} image
      * @memberof OpenSeadragon.Tile#
      * @deprecated
-     * @return {Image}
+     * @returns {Image}
      */
     get image() {
         $.console.error("[Tile.image] property has been deprecated. Use [Tile.prototype.getImage] instead.");
@@ -344,7 +344,7 @@ $.Tile.prototype = {
 
     /**
      * Get the Image object for this tile.
-     * @return {Image}
+     * @returns {Image}
      */
     getImage: function() {
         return this.cacheImageRecord.getImage();
@@ -353,7 +353,7 @@ $.Tile.prototype = {
     /**
      * Get the CanvasRenderingContext2D instance for tile image data drawn
      * onto Canvas if enabled and available
-     * @return {CanvasRenderingContext2D}
+     * @returns {CanvasRenderingContext2D}
      */
     getCanvasContext: function() {
         return this.context2D || this.cacheImageRecord.getRenderedContext();
@@ -469,7 +469,7 @@ $.Tile.prototype = {
     /**
      * Get the ratio between current and original size.
      * @function
-     * @return {Float}
+     * @returns {Float}
      */
     getScaleForEdgeSmoothing: function() {
         var context;
@@ -491,7 +491,7 @@ $.Tile.prototype = {
      * Needed to avoid swimming and twitching.
      * @function
      * @param {Number} [scale=1] - Scale to be applied to position.
-     * @return {OpenSeadragon.Point}
+     * @returns {OpenSeadragon.Point}
      */
     getTranslationForEdgeSmoothing: function(scale, canvasSize, sketchCanvasSize) {
         // The translation vector must have positive values, otherwise the image goes a bit off

src/tiledimage.js

@@ -443,7 +443,7 @@ $.extend($.TiledImage.prototype, $.EventSource.prototype, /** @lends OpenSeadrag
      * @param {Number|OpenSeadragon.Point} viewerX - The X coordinate or point in viewport coordinate system.
      * @param {Number} [viewerY] - The Y coordinate in viewport coordinate system.
      * @param {Boolean} [current=false] - Pass true to use the current location; false for target location.
-     * @return {OpenSeadragon.Point} A point representing the coordinates in the image.
+     * @returns {OpenSeadragon.Point} A point representing the coordinates in the image.
      */
     viewportToImageCoordinates: function(viewerX, viewerY, current) {
         var point;
@@ -478,7 +478,7 @@ $.extend($.TiledImage.prototype, $.EventSource.prototype, /** @lends OpenSeadrag
      * @param {Number|OpenSeadragon.Point} imageX - The X coordinate or point in image coordinate system.
      * @param {Number} [imageY] - The Y coordinate in image coordinate system.
      * @param {Boolean} [current=false] - Pass true to use the current location; false for target location.
-     * @return {OpenSeadragon.Point} A point representing the coordinates in the viewport.
+     * @returns {OpenSeadragon.Point} A point representing the coordinates in the viewport.
      */
     imageToViewportCoordinates: function(imageX, imageY, current) {
         if (imageX instanceof $.Point) {
@@ -509,7 +509,7 @@ $.extend($.TiledImage.prototype, $.EventSource.prototype, /** @lends OpenSeadrag
      * @param {Number} [pixelWidth] - The width in pixel of the rectangle.
      * @param {Number} [pixelHeight] - The height in pixel of the rectangle.
      * @param {Boolean} [current=false] - Pass true to use the current location; false for target location.
-     * @return {OpenSeadragon.Rect} A rect representing the coordinates in the viewport.
+     * @returns {OpenSeadragon.Rect} A rect representing the coordinates in the viewport.
      */
     imageToViewportRectangle: function(imageX, imageY, pixelWidth, pixelHeight, current) {
         var rect = imageX;
@@ -541,7 +541,7 @@ $.extend($.TiledImage.prototype, $.EventSource.prototype, /** @lends OpenSeadrag
      * @param {Number} [pointWidth] - The width in viewport coordinate system.
      * @param {Number} [pointHeight] - The height in viewport coordinate system.
      * @param {Boolean} [current=false] - Pass true to use the current location; false for target location.
-     * @return {OpenSeadragon.Rect} A rect representing the coordinates in the image.
+     * @returns {OpenSeadragon.Rect} A rect representing the coordinates in the image.
      */
     viewportToImageRectangle: function( viewerX, viewerY, pointWidth, pointHeight, current ) {
         var rect = viewerX;

src/tilesource.js

@@ -579,7 +579,7 @@ $.TileSource.prototype = {
      * @param {String|Object|Array|Document} data
      * @param {String} url - the url the data was loaded
      *      from if any.
-     * @return {Boolean}
+     * @returns {Boolean}
      */
     supports: function( data, url ) {
         return false;
@@ -598,7 +598,7 @@ $.TileSource.prototype = {
      *      from if any.
      * @param {String} postData - HTTP POST data in k=v&k2=v2... form or null value obtained from
      *      the protocol URL after '#' sign if flag splitHashDataForPost set to 'true'
-     * @return {Object} options - A dictionary of keyword arguments sufficient
+     * @returns {Object} options - A dictionary of keyword arguments sufficient
      *      to configure the tile source constructor (include all values you want to
      *      instantiate the TileSource subclass with - what _options_ object should contain).
      * @throws {Error}
@@ -649,7 +649,7 @@ $.TileSource.prototype = {
      * @param {Number} level
      * @param {Number} x
      * @param {Number} y
-     * @return {*|null} post data to send with tile configuration request
+     * @returns {*|null} post data to send with tile configuration request
      */
     getTilePostData: function( level, x, y ) {
         return null;
@@ -716,7 +716,7 @@ $.TileSource.prototype = {
 
     /**
      * Decide whether tiles have transparency: this is crucial for correct images blending.
-     * @return {boolean} true if the image has transparency
+     * @returns {boolean} true if the image has transparency
      */
     hasTransparency: function(context2D, url, ajaxHeaders, post) {
         return !!context2D || url.match('.png');
@@ -862,7 +862,7 @@ $.TileSource.prototype = {
      * Raw data getter
      * Note that if you override any of *TileCache() functions, you should override all of them.
      * @param {object} cacheObject context cache object
-     * @return {*} cache data
+     * @returns {*} cache data
      */
     getTileCacheData: function(cacheObject) {
         return cacheObject._data;
@@ -874,7 +874,7 @@ $.TileSource.prototype = {
      *  - div HTML rendering relies on image element presence
      * Note that if you override any of *TileCache() functions, you should override all of them.
      *  @param {object} cacheObject context cache object
-     *  @return {Image} cache data as an Image
+     *  @returns {Image} cache data as an Image
      */
     getTileCacheDataAsImage: function(cacheObject) {
         return cacheObject._data; //the data itself by default is Image
@@ -886,7 +886,7 @@ $.TileSource.prototype = {
      *    convert the data to a canvas and return it's 2D context
      * Note that if you override any of *TileCache() functions, you should override all of them.
      * @param {object} cacheObject context cache object
-     * @return {CanvasRenderingContext2D} context of the canvas representation of the cache data
+     * @returns {CanvasRenderingContext2D} context of the canvas representation of the cache data
      */
     getTileCacheDataAsContext2D: function(cacheObject) {
         if (!cacheObject._renderedContext) {

src/tmstilesource.js

@@ -112,7 +112,7 @@ $.extend( $.TmsTileSource.prototype, $.TileSource.prototype, /** @lends OpenSead
      * @param {Object} data - the raw configuration
      * @param {String} url - the url the data was retrieved from if any.
      * @param {String} postData - HTTP POST data in k=v&k2=v2... form or null
-     * @return {Object} options - A dictionary of keyword arguments sufficient
+     * @returns {Object} options - A dictionary of keyword arguments sufficient
      *      to configure this tile sources constructor.
      */
     configure: function( data, url, postData ){

src/viewer.js

@@ -182,7 +182,7 @@ $.Viewer = function( options ) {
         navImages:      null,
 
         //interface button controls
-        buttons:        null,
+        buttonGroup:        null,
 
         //TODO: this is defunct so safely remove it
         profiler:       null
@@ -493,7 +493,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
 
     /**
      * @function
-     * @return {Boolean}
+     * @returns {Boolean}
      */
     isOpen: function () {
         return !!this.world.getItemCount();
@@ -531,7 +531,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
      * of the options parameter for {@link OpenSeadragon.Viewer#addTiledImage}.
      * @param {Number} initialPage - If sequenceMode is true, display this page initially
      * for the given tileSources. If specified, will overwrite the Viewer's existing initialPage property.
-     * @return {OpenSeadragon.Viewer} Chainable.
+     * @returns {OpenSeadragon.Viewer} Chainable.
      * @fires OpenSeadragon.Viewer.event:open
      * @fires OpenSeadragon.Viewer.event:open-failed
      */
@@ -703,7 +703,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
 
     /**
      * @function
-     * @return {OpenSeadragon.Viewer} Chainable.
+     * @returns {OpenSeadragon.Viewer} Chainable.
      * @fires OpenSeadragon.Viewer.event:close
      */
     close: function ( ) {
@@ -845,7 +845,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
 
     /**
      * @function
-     * @return {Boolean}
+     * @returns {Boolean}
      */
     isMouseNavEnabled: function () {
         return this.innerTracker.isTracking();
@@ -854,7 +854,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
     /**
      * @function
      * @param {Boolean} enabled - true to enable, false to disable
-     * @return {OpenSeadragon.Viewer} Chainable.
+     * @returns {OpenSeadragon.Viewer} Chainable.
      * @fires OpenSeadragon.Viewer.event:mouse-enabled
      */
     setMouseNavEnabled: function( enabled ){
@@ -877,7 +877,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
 
     /**
      * @function
-     * @return {Boolean}
+     * @returns {Boolean}
      */
     areControlsEnabled: function () {
         var enabled = this.controls.length,
@@ -894,7 +894,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
      *
      * @function
      * @param {Boolean} true to show, false to hide.
-     * @return {OpenSeadragon.Viewer} Chainable.
+     * @returns {OpenSeadragon.Viewer} Chainable.
      * @fires OpenSeadragon.Viewer.event:controls-enabled
      */
     setControlsEnabled: function( enabled ) {
@@ -935,7 +935,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
 
     /**
      * @function
-     * @return {Boolean}
+     * @returns {Boolean}
      */
     isFullPage: function () {
         return THIS[ this.hash ].fullPage;
@@ -947,7 +947,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
      * @function
      * @param {Boolean} fullPage
      *      If true, enter full page mode.  If false, exit full page mode.
-     * @return {OpenSeadragon.Viewer} Chainable.
+     * @returns {OpenSeadragon.Viewer} Chainable.
      * @fires OpenSeadragon.Viewer.event:pre-full-page
      * @fires OpenSeadragon.Viewer.event:full-page
      */
@@ -1162,7 +1162,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
      * @function
      * @param {Boolean} fullScreen
      *      If true, enter full screen mode.  If false, exit full screen mode.
-     * @return {OpenSeadragon.Viewer} Chainable.
+     * @returns {OpenSeadragon.Viewer} Chainable.
      * @fires OpenSeadragon.Viewer.event:pre-full-screen
      * @fires OpenSeadragon.Viewer.event:full-screen
      */
@@ -1257,7 +1257,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
 
     /**
      * @function
-     * @return {Boolean}
+     * @returns {Boolean}
      */
     isVisible: function () {
         return this.container.style.visibility !== "hidden";
@@ -1276,7 +1276,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
     /**
      * @function
      * @param {Boolean} visible
-     * @return {OpenSeadragon.Viewer} Chainable.
+     * @returns {OpenSeadragon.Viewer} Chainable.
      * @fires OpenSeadragon.Viewer.event:visible
      */
     setVisible: function( visible ){
@@ -1657,7 +1657,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
 
     /**
      * @function
-     * @return {OpenSeadragon.Viewer} Chainable.
+     * @returns {OpenSeadragon.Viewer} Chainable.
      */
     bindSequenceControls: function(){
 
@@ -1746,7 +1746,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
 
     /**
      * @function
-     * @return {OpenSeadragon.Viewer} Chainable.
+     * @returns {OpenSeadragon.Viewer} Chainable.
      */
     bindStandardControls: function(){
         //////////////////////////////////////////////////////////////////////////
@@ -1928,7 +1928,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
     /**
      * Gets the active page of a sequence
      * @function
-     * @return {Number}
+     * @returns {Number}
      */
     currentPage: function() {
         return this._sequenceIndex;
@@ -1936,7 +1936,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
 
     /**
      * @function
-     * @return {OpenSeadragon.Viewer} Chainable.
+     * @returns {OpenSeadragon.Viewer} Chainable.
      * @fires OpenSeadragon.Viewer.event:page
      */
     goToPage: function( page ){
@@ -1985,7 +1985,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.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.
-     * @return {OpenSeadragon.Viewer} Chainable.
+     * @returns {OpenSeadragon.Viewer} Chainable.
      * @fires OpenSeadragon.Viewer.event:add-overlay
      */
     addOverlay: function( element, location, placement, onDraw ) {
@@ -2043,7 +2043,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
      * @param {OpenSeadragon.Placement} [placement=OpenSeadragon.Placement.TOP_LEFT] - The position of the
      *      viewport which the location coordinates will be treated as relative
      *      to.
-     * @return {OpenSeadragon.Viewer} Chainable.
+     * @returns {OpenSeadragon.Viewer} Chainable.
      * @fires OpenSeadragon.Viewer.event:update-overlay
      */
     updateOverlay: function( element, location, placement ) {
@@ -2084,7 +2084,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
      * @method
      * @param {Element|String} element - A reference to the element or an
      *      element id which represent the ovelay content to be removed.
-     * @return {OpenSeadragon.Viewer} Chainable.
+     * @returns {OpenSeadragon.Viewer} Chainable.
      * @fires OpenSeadragon.Viewer.event:remove-overlay
      */
     removeOverlay: function( element ) {
@@ -2120,7 +2120,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
      * Removes all currently configured Overlays from this Viewer and schedules
      * an update.
      * @method
-     * @return {OpenSeadragon.Viewer} Chainable.
+     * @returns {OpenSeadragon.Viewer} Chainable.
      * @fires OpenSeadragon.Viewer.event:clear-overlay
      */
     clearOverlays: function() {
@@ -2147,7 +2147,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
      * @method
      * @param {Element|String} element - A reference to the element or an
      *      element id which represents the overlay content.
-     * @return {OpenSeadragon.Overlay} the matching overlay or null if none found.
+     * @returns {OpenSeadragon.Overlay} the matching overlay or null if none found.
      */
     getOverlayById: function( element ) {
         var i;
@@ -2228,7 +2228,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
      * Gets this viewer's gesture settings for the given pointer device type.
      * @method
      * @param {String} type - The pointer device type to get the gesture settings for ("mouse", "touch", "pen", etc.).
-     * @return {OpenSeadragon.GestureSettings}
+     * @returns {OpenSeadragon.GestureSettings}
      */
     gestureSettingsByDeviceType: function ( type ) {
         switch ( type ) {

src/viewport.js

@@ -172,7 +172,7 @@ $.Viewport.prototype = {
      * Updates the viewport's home bounds and constraints for the given content size.
      * @function
      * @param {OpenSeadragon.Point} contentSize - size of the content in content units
-     * @return {OpenSeadragon.Viewport} Chainable.
+     * @returns {OpenSeadragon.Viewport} Chainable.
      * @fires OpenSeadragon.Viewer.event:reset-size
      */
     resetContentSize: function(contentSize) {
@@ -511,7 +511,7 @@ $.Viewport.prototype = {
      * @function
      * @private
      * @param {OpenSeadragon.Rect} bounds
-     * @return {OpenSeadragon.Rect} constrained bounds.
+     * @returns {OpenSeadragon.Rect} constrained bounds.
      */
     _applyBoundaryConstraints: function(bounds) {
         var newBounds = new $.Rect(
@@ -615,7 +615,7 @@ $.Viewport.prototype = {
      * zooming and panning to the closest acceptable zoom and location.
      * @function
      * @param {Boolean} [immediately=false]
-     * @return {OpenSeadragon.Viewport} Chainable.
+     * @returns {OpenSeadragon.Viewport} Chainable.
      * @fires OpenSeadragon.Viewer.event:constrain
      */
     applyConstraints: function(immediately) {
@@ -644,7 +644,7 @@ $.Viewport.prototype = {
      * Equivalent to {@link OpenSeadragon.Viewport#applyConstraints}
      * @function
      * @param {Boolean} [immediately=false]
-     * @return {OpenSeadragon.Viewport} Chainable.
+     * @returns {OpenSeadragon.Viewport} Chainable.
      * @fires OpenSeadragon.Viewer.event:constrain
      */
     ensureVisible: function(immediately) {
@@ -656,7 +656,7 @@ $.Viewport.prototype = {
      * @private
      * @param {OpenSeadragon.Rect} bounds
      * @param {Object} options (immediately=false, constraints=false)
-     * @return {OpenSeadragon.Viewport} Chainable.
+     * @returns {OpenSeadragon.Viewport} Chainable.
      */
     _fitBounds: function(bounds, options) {
         options = options || {};
@@ -737,7 +737,7 @@ $.Viewport.prototype = {
      * @function
      * @param {OpenSeadragon.Rect} bounds
      * @param {Boolean} [immediately=false]
-     * @return {OpenSeadragon.Viewport} Chainable.
+     * @returns {OpenSeadragon.Viewport} Chainable.
      */
     fitBounds: function(bounds, immediately) {
         return this._fitBounds(bounds, {
@@ -756,7 +756,7 @@ $.Viewport.prototype = {
      * @function
      * @param {OpenSeadragon.Rect} bounds
      * @param {Boolean} [immediately=false]
-     * @return {OpenSeadragon.Viewport} Chainable.
+     * @returns {OpenSeadragon.Viewport} Chainable.
      */
     fitBoundsWithConstraints: function(bounds, immediately) {
         return this._fitBounds(bounds, {
@@ -768,7 +768,7 @@ $.Viewport.prototype = {
     /**
      * Zooms so the image just fills the viewer vertically.
      * @param {Boolean} immediately
-     * @return {OpenSeadragon.Viewport} Chainable.
+     * @returns {OpenSeadragon.Viewport} Chainable.
      */
     fitVertically: function(immediately) {
         var box = new $.Rect(
@@ -782,7 +782,7 @@ $.Viewport.prototype = {
     /**
      * Zooms so the image just fills the viewer horizontally.
      * @param {Boolean} immediately
-     * @return {OpenSeadragon.Viewport} Chainable.
+     * @returns {OpenSeadragon.Viewport} Chainable.
      */
     fitHorizontally: function(immediately) {
         var box = new $.Rect(
@@ -798,7 +798,7 @@ $.Viewport.prototype = {
      * Returns bounds taking constraints into account
      * Added to improve constrained panning
      * @param {Boolean} current - Pass true for the current location; defaults to false (target location).
-     * @return {OpenSeadragon.Viewport} Chainable.
+     * @returns {OpenSeadragon.Viewport} Chainable.
      */
     getConstrainedBounds: function(current) {
         var bounds,
@@ -815,7 +815,7 @@ $.Viewport.prototype = {
      * @function
      * @param {OpenSeadragon.Point} delta
      * @param {Boolean} immediately
-     * @return {OpenSeadragon.Viewport} Chainable.
+     * @returns {OpenSeadragon.Viewport} Chainable.
      * @fires OpenSeadragon.Viewer.event:pan
      */
     panBy: function( delta, immediately ) {
@@ -830,7 +830,7 @@ $.Viewport.prototype = {
      * @function
      * @param {OpenSeadragon.Point} center
      * @param {Boolean} immediately
-     * @return {OpenSeadragon.Viewport} Chainable.
+     * @returns {OpenSeadragon.Viewport} Chainable.
      * @fires OpenSeadragon.Viewer.event:pan
      */
     panTo: function( center, immediately ) {
@@ -865,7 +865,7 @@ $.Viewport.prototype = {
 
     /**
      * @function
-     * @return {OpenSeadragon.Viewport} Chainable.
+     * @returns {OpenSeadragon.Viewport} Chainable.
      * @fires OpenSeadragon.Viewer.event:zoom
      */
     zoomBy: function(factor, refPoint, immediately) {
@@ -880,7 +880,7 @@ $.Viewport.prototype = {
      * @param {OpenSeadragon.Point} [refPoint] The point which will stay at
      * the same screen location. Defaults to the viewport center.
      * @param {Boolean} [immediately=false]
-     * @return {OpenSeadragon.Viewport} Chainable.
+     * @returns {OpenSeadragon.Viewport} Chainable.
      * @fires OpenSeadragon.Viewer.event:zoom
      */
     zoomTo: function(zoom, refPoint, immediately) {
@@ -929,7 +929,7 @@ $.Viewport.prototype = {
      * @param {Number} degrees The degrees to set the rotation to.
      * @param {Boolean} [immediately=false] Whether to animate to the new angle
      * or rotate immediately.
-     * @return {OpenSeadragon.Viewport} Chainable.
+     * @returns {OpenSeadragon.Viewport} Chainable.
      */
     setRotation: function(degrees, immediately) {
         if (!this.viewer || !this.viewer.drawer.canRotate()) {
@@ -980,7 +980,7 @@ $.Viewport.prototype = {
      * Gets the current rotation in degrees.
      * @function
      * @param {Boolean} [current=false] True for current rotation, false for target.
-     * @return {Number} The current rotation in degrees.
+     * @returns {Number} The current rotation in degrees.
      */
     getRotation: function(current) {
         return current ?
@@ -990,7 +990,7 @@ $.Viewport.prototype = {
 
     /**
      * @function
-     * @return {OpenSeadragon.Viewport} Chainable.
+     * @returns {OpenSeadragon.Viewport} Chainable.
      * @fires OpenSeadragon.Viewer.event:resize
      */
     resize: function( newContainerSize, maintain ) {
@@ -1241,7 +1241,7 @@ $.Viewport.prototype = {
      * @param {(OpenSeadragon.Point|Number)} viewerX either a point or the X
      * coordinate in viewport coordinate system.
      * @param {Number} [viewerY] Y coordinate in viewport coordinate system.
-     * @return {OpenSeadragon.Point} a point representing the coordinates in the image.
+     * @returns {OpenSeadragon.Point} a point representing the coordinates in the image.
      */
     viewportToImageCoordinates: function(viewerX, viewerY) {
         if (viewerX instanceof $.Point) {
@@ -1287,7 +1287,7 @@ $.Viewport.prototype = {
      * @param {(OpenSeadragon.Point | Number)} imageX the point or the
      * X coordinate in image coordinate system.
      * @param {Number} [imageY] Y coordinate in image coordinate system.
-     * @return {OpenSeadragon.Point} a point representing the coordinates in the viewport.
+     * @returns {OpenSeadragon.Point} a point representing the coordinates in the viewport.
      */
     imageToViewportCoordinates: function(imageX, imageY) {
         if (imageX instanceof $.Point) {
@@ -1618,7 +1618,7 @@ $.Viewport.prototype = {
     /**
      * Toggles flip state and demands a new drawing on navigator and viewer objects.
      * @function
-     * @return {OpenSeadragon.Viewport} Chainable.
+     * @returns {OpenSeadragon.Viewport} Chainable.
      */
     toggleFlip: function() {
       this.setFlip(!this.getFlip());
@@ -1628,7 +1628,7 @@ $.Viewport.prototype = {
     /**
      * Get flip state stored on viewport.
      * @function
-     * @return {Boolean} Flip state.
+     * @returns {Boolean} Flip state.
      */
     getFlip: function() {
       return this.flipped;
@@ -1638,7 +1638,7 @@ $.Viewport.prototype = {
      * Sets flip state according to the state input argument.
      * @function
      * @param {Boolean} state - Flip state to set.
-     * @return {OpenSeadragon.Viewport} Chainable.
+     * @returns {OpenSeadragon.Viewport} Chainable.
      */
     setFlip: function( state ) {
       if ( this.flipped === state ) {

src/zoomifytilesource.js

@@ -123,7 +123,7 @@
          * @param {Object} data - the raw configuration
          * @param {String} url - the url the data was retrieved from if any.
          * @param {String} postData - HTTP POST data in k=v&k2=v2... form or null
-         * @return {Object} options - A dictionary of keyword arguments sufficient
+         * @returns {Object} options - A dictionary of keyword arguments sufficient
          *      to configure this tile sources constructor.
          */
         configure: function(data, url, postData) {