Merge pull request #2466 from pearcetm/fix-docs

fix jsdoc formatting for drawer classes

src/canvasdrawer.js

@@ -34,9 +34,10 @@
 
 (function( $ ){
 
+    const OpenSeadragon = $; // (re)alias back to OpenSeadragon for JSDoc
 /**
- * @class CanvasDrawer
+ * @class OpenSeadragon.CanvasDrawer
- * @memberof OpenSeadragon
+ * @extends OpenSeadragon.DrawerBase
  * @classdesc Default implementation of CanvasDrawer for an {@link OpenSeadragon.Viewer}.
  * @param {Object} options - Options for this Drawer.
  * @param {OpenSeadragon.Viewer} options.viewer - The Viewer that owns this Drawer.
@@ -45,14 +46,28 @@
  * @param {Number} [options.debugGridColor] - See debugGridColor in {@link OpenSeadragon.Options} for details.
  */
 
-class CanvasDrawer extends $.DrawerBase{
+class CanvasDrawer extends OpenSeadragon.DrawerBase{
     constructor(options){
         super(options);
 
+        /**
+         * The HTML element (canvas) that this drawer uses for drawing
+         * @member {Element} canvas
+         * @memberof OpenSeadragon.CanvasDrawer#
+         */
+
+        /**
+         * The parent element of this Drawer instance, passed in when the Drawer was created.
+         * The parent of {@link OpenSeadragon.WebGLDrawer#canvas}.
+         * @member {Element} container
+         * @memberof OpenSeadragon.CanvasDrawer#
+         */
+
         /**
          * 2d drawing context for {@link OpenSeadragon.CanvasDrawer#canvas}.
          * @member {Object} context
          * @memberof OpenSeadragon.CanvasDrawer#
+         * @private
          */
         this.context = this.canvas.getContext( '2d' );
 

src/drawerbase.js

@@ -34,17 +34,18 @@
 
 (function( $ ){
 
+    const OpenSeadragon = $; // (re)alias back to OpenSeadragon for JSDoc
 /**
- * @class DrawerBase
+ * @class OpenSeadragon.DrawerBase
- * @memberof OpenSeadragon
  * @classdesc Base class for Drawers that handle rendering of tiles for an {@link OpenSeadragon.Viewer}.
  * @param {Object} options - Options for this Drawer.
  * @param {OpenSeadragon.Viewer} options.viewer - The Viewer that owns this Drawer.
  * @param {OpenSeadragon.Viewport} options.viewport - Reference to Viewer viewport.
- * @param {Element} options.element - Parent element.
+ * @param {HTMLElement} options.element - Parent element.
+ * @abstract
  */
 
-$.DrawerBase = class DrawerBase{
+OpenSeadragon.DrawerBase = class DrawerBase{
     constructor(options){
         $.console.assert( options.viewer, "[Drawer] options.viewer is required" );
         $.console.assert( options.viewport, "[Drawer] options.viewport is required" );
@@ -55,12 +56,6 @@ $.DrawerBase = class DrawerBase{
         this.debugGridColor = typeof options.debugGridColor === 'string' ? [options.debugGridColor] : options.debugGridColor || $.DEFAULT_SETTINGS.debugGridColor;
         this.options = options.options || {};
 
-        /**
-         * The parent element of this Drawer instance, passed in when the Drawer was created.
-         * The parent of {@link OpenSeadragon.DrawerBase#canvas}.
-         * @member {Element} container
-         * @memberof OpenSeadragon.DrawerBase#
-         */
         this.container  = $.getElement( options.element );
 
         this._renderingTarget = this._createDrawingElement();
@@ -95,7 +90,8 @@ $.DrawerBase = class DrawerBase{
     }
 
     /**
-     * @returns {String|undefined} What type of drawer this is.
+     * @abstract
+     * @returns {String | undefined} What type of drawer this is. Must be overridden by extending classes.
      */
     getType(){
         $.console.error('Drawer.getType must be implemented by child class');
@@ -103,15 +99,17 @@ $.DrawerBase = class DrawerBase{
     }
 
     /**
-     * @returns {Boolean} whether the drawer implementation is supported by the browser
+     * @abstract
+     * @returns {Boolean} Whether the drawer implementation is supported by the browser. Must be overridden by extending classes.
      */
     static isSupported() {
         $.console.error('Drawer.isSupported must be implemented by child class');
     }
 
     /**
-     * create the HTML element (e.g. canvas, div) that the image will be drawn into
+     * @abstract
      * @returns {Element} the element to draw into
+     * @private
      */
     _createDrawingElement() {
         $.console.error('Drawer._createDrawingElement must be implemented by child class');
@@ -119,13 +117,16 @@ $.DrawerBase = class DrawerBase{
     }
 
     /**
-     * @param {Array} tiledImages - An array of TiledImages that are ready to be drawn
+     * @abstract
+     * @param {Array} tiledImages - An array of TiledImages that are ready to be drawn.
+     * @private
      */
     draw(tiledImages) {
         $.console.error('Drawer.draw must be implemented by child class');
     }
 
     /**
+     * @abstract
      * @returns {Boolean} True if rotation is supported.
      */
     canRotate() {
@@ -133,7 +134,7 @@ $.DrawerBase = class DrawerBase{
     }
 
     /**
-     * Destroy the drawer (unload current loaded tiles)
+     * @abstract
      */
     destroy() {
         $.console.error('Drawer.destroy must be implemented by child class');
@@ -141,6 +142,7 @@ $.DrawerBase = class DrawerBase{
 
     /**
      * @returns {Boolean} Whether this drawer requires enforcing minimum tile overlap to avoid showing seams.
+     * @private
      */
     minimumOverlapRequired() {
         return false;
@@ -148,9 +150,7 @@ $.DrawerBase = class DrawerBase{
 
 
     /**
-     * Turns image smoothing on or off for this viewer. Note: Ignored in some (especially older) browsers that do not support this property.
+     * @abstract
-     *
-     * @function
      * @param {Boolean} [imageSmoothingEnabled] - Whether or not the image is
      * drawn smoothly on the canvas; see imageSmoothingEnabled in
      * {@link OpenSeadragon.Options} for more explanation.

src/htmldrawer.js

@@ -34,9 +34,11 @@
 
 (function( $ ){
 
+    const OpenSeadragon = $; // alias back for JSDoc
+
 /**
- * @class HTMLDrawer
+ * @class OpenSeadragon.HTMLDrawer
- * @memberof OpenSeadragon
+ * @extends OpenSeadragon.DrawerBase
  * @classdesc HTML-based implementation of DrawerBase for an {@link OpenSeadragon.Viewer}.
  * @param {Object} options - Options for this Drawer.
  * @param {OpenSeadragon.Viewer} options.viewer - The Viewer that owns this Drawer.
@@ -45,10 +47,23 @@
  * @param {Number} [options.debugGridColor] - See debugGridColor in {@link OpenSeadragon.Options} for details.
  */
 
-class HTMLDrawer extends $.DrawerBase{
+class HTMLDrawer extends OpenSeadragon.DrawerBase{
     constructor(options){
         super(options);
 
+        /**
+         * The HTML element (div) that this drawer uses for drawing
+         * @member {Element} canvas
+         * @memberof OpenSeadragon.HTMLDrawer#
+         */
+
+        /**
+         * The parent element of this Drawer instance, passed in when the Drawer was created.
+         * The parent of {@link OpenSeadragon.WebGLDrawer#canvas}.
+         * @member {Element} container
+         * @memberof OpenSeadragon.HTMLDrawer#
+         */
+
         // Reject listening for the tile-drawing event, which this drawer does not fire
         this.viewer.rejectEventHandler("tile-drawing", "The HTMLDrawer does not raise the tile-drawing event");
         // Since the tile-drawn event is fired by this drawer, make sure handlers can be added for it
@@ -62,6 +77,10 @@ class HTMLDrawer extends $.DrawerBase{
         return true;
     }
 
+    /**
+     *
+     * @returns 'html'
+     */
     getType(){
         return 'html';
     }
@@ -111,9 +130,7 @@ class HTMLDrawer extends $.DrawerBase{
     }
 
     /**
-     * Turns image smoothing on or off for this viewer. Note: Ignored by HTML Drawer
+     * This function is ignored by the HTML Drawer. Implementing it is required by DrawerBase.
-     *
-     * @function
      * @param {Boolean} [imageSmoothingEnabled] - Whether or not the image is
      * drawn smoothly on the canvas; see imageSmoothingEnabled in
      * {@link OpenSeadragon.Options} for more explanation.

src/webgldrawer.js

@@ -35,9 +35,10 @@
 
 (function( $ ){
 
+    const OpenSeadragon = $; // alias for JSDoc
+
    /**
-    * @class WebGLDrawer
+    * @class OpenSeadragon.WebGLDrawer
-    * @memberof OpenSeadragon
     * @classdesc Default implementation of WebGLDrawer for an {@link OpenSeadragon.Viewer}. The WebGLDrawer
     * loads tile data as textures to the graphics card as soon as it is available (via the tile-ready event),
     * and unloads the data (via the image-unloaded event). The drawer utilizes a context-dependent two pass drawing pipeline.
@@ -56,43 +57,55 @@
     * @param {Number} [options.debugGridColor] - See debugGridColor in {@link OpenSeadragon.Options} for details.
     */
 
-    $.WebGLDrawer = class WebGLDrawer extends OpenSeadragon.DrawerBase{
+    OpenSeadragon.WebGLDrawer = class WebGLDrawer extends OpenSeadragon.DrawerBase{
         constructor(options){
            super(options);
 
-           this.destroyed = false;
+            /**
-           // private members
+             * The HTML element (canvas) that this drawer uses for drawing
+             * @member {Element} canvas
+             * @memberof OpenSeadragon.WebGLDrawer#
+             */
 
-           this._TextureMap = new Map();
+            /**
-           this._TileMap = new Map();
+             * The parent element of this Drawer instance, passed in when the Drawer was created.
+             * The parent of {@link OpenSeadragon.WebGLDrawer#canvas}.
+             * @member {Element} container
+             * @memberof OpenSeadragon.WebGLDrawer#
+             */
 
-           this._gl = null;
+            // private members
-           this._firstPass = null;
+            this._destroyed = false;
-           this._secondPass = null;
+            this._TextureMap = new Map();
-           this._glFrameBuffer = null;
+            this._TileMap = new Map();
-           this._renderToTexture = null;
-           this._glFramebufferToCanvasTransform = null;
-           this._outputCanvas = null;
-           this._outputContext = null;
-           this._clippingCanvas = null;
-           this._clippingContext = null;
-           this._renderingCanvas = null;
 
-           // Add listeners for events that require modifying the scene or camera
+            this._gl = null;
-           this.viewer.addHandler("tile-ready", ev => this._tileReadyHandler(ev));
+            this._firstPass = null;
-           this.viewer.addHandler("image-unloaded", ev => this._imageUnloadedHandler(ev));
+            this._secondPass = null;
+            this._glFrameBuffer = null;
+            this._renderToTexture = null;
+            this._glFramebufferToCanvasTransform = null;
+            this._outputCanvas = null;
+            this._outputContext = null;
+            this._clippingCanvas = null;
+            this._clippingContext = null;
+            this._renderingCanvas = null;
 
-           // Reject listening for the tile-drawing and tile-drawn events, which this drawer does not fire
+            // Add listeners for events that require modifying the scene or camera
-           this.viewer.rejectEventHandler("tile-drawn", "The WebGLDrawer does not raise the tile-drawn event");
+            this.viewer.addHandler("tile-ready", ev => this._tileReadyHandler(ev));
-           this.viewer.rejectEventHandler("tile-drawing", "The WebGLDrawer does not raise the tile-drawing event");
+            this.viewer.addHandler("image-unloaded", ev => this._imageUnloadedHandler(ev));
 
-           // this.viewer and this.canvas are part of the public DrawerBase API
+            // Reject listening for the tile-drawing and tile-drawn events, which this drawer does not fire
-           // and are defined by the parent DrawerBase class. Additional setup is done by
+            this.viewer.rejectEventHandler("tile-drawn", "The WebGLDrawer does not raise the tile-drawn event");
-           // the private _setupCanvases and _setupRenderer functions.
+            this.viewer.rejectEventHandler("tile-drawing", "The WebGLDrawer does not raise the tile-drawing event");
-           this._setupCanvases();
-           this._setupRenderer();
 
-           this.context = this._outputContext; // API required by tests
+            // this.viewer and this.canvas are part of the public DrawerBase API
+            // and are defined by the parent DrawerBase class. Additional setup is done by
+            // the private _setupCanvases and _setupRenderer functions.
+            this._setupCanvases();
+            this._setupRenderer();
+
+            this.context = this._outputContext; // API required by tests
 
        }
 
@@ -101,7 +114,7 @@
         * Clean up the renderer, removing all resources
         */
         destroy(){
-            if(this.destroyed){
+            if(this._destroyed){
                 return;
             }
             // clear all resources used by the renderer, geometries, textures etc
@@ -145,13 +158,13 @@
             this._gl = null;
 
             // set our destroyed flag to true
-            this.destroyed = true;
+            this._destroyed = true;
         }
 
         // Public API required by all Drawer implementations
         /**
         *
-        * @returns {Boolean} true if the drawer supports rotation
+        * @returns {Boolean} true
         */
         canRotate(){
             return true;
@@ -172,6 +185,10 @@
             return !!( webglContext );
         }
 
+        /**
+         *
+         * @returns 'webgl'
+         */
         getType(){
             return 'webgl';
         }
@@ -393,7 +410,7 @@
 
         // Public API required by all Drawer implementations
         /**
-        * Set the context2d imageSmoothingEnabled parameter
+        * Required by DrawerBase, but has no effect on WebGLDrawer.
         * @param {Boolean} enabled
         */
         setImageSmoothingEnabled(enabled){