From 23e50b60386e81e11f5ff10974df5d98847f5236 Mon Sep 17 00:00:00 2001 From: Tom Date: Thu, 1 Feb 2024 14:24:25 -0500 Subject: [PATCH] fix jsdoc formatting for drawer classes --- src/canvasdrawer.js | 21 +++++++++-- src/drawerbase.js | 36 +++++++++---------- src/htmldrawer.js | 29 ++++++++++++---- src/webgldrawer.js | 85 +++++++++++++++++++++++++++------------------ 4 files changed, 110 insertions(+), 61 deletions(-) diff --git a/src/canvasdrawer.js b/src/canvasdrawer.js index a637fb39..b60524aa 100644 --- a/src/canvasdrawer.js +++ b/src/canvasdrawer.js @@ -34,9 +34,10 @@ (function( $ ){ + const OpenSeadragon = $; // (re)alias back to OpenSeadragon for JSDoc /** - * @class CanvasDrawer - * @memberof OpenSeadragon + * @class OpenSeadragon.CanvasDrawer + * @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 () 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' ); diff --git a/src/drawerbase.js b/src/drawerbase.js index 3206c69f..29d7a3b4 100644 --- a/src/drawerbase.js +++ b/src/drawerbase.js @@ -34,17 +34,18 @@ (function( $ ){ + const OpenSeadragon = $; // (re)alias back to OpenSeadragon for JSDoc /** - * @class DrawerBase - * @memberof OpenSeadragon + * @class OpenSeadragon.DrawerBase * @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. - * - * @function + * @abstract * @param {Boolean} [imageSmoothingEnabled] - Whether or not the image is * drawn smoothly on the canvas; see imageSmoothingEnabled in * {@link OpenSeadragon.Options} for more explanation. diff --git a/src/htmldrawer.js b/src/htmldrawer.js index a9030702..0f0fc259 100644 --- a/src/htmldrawer.js +++ b/src/htmldrawer.js @@ -34,9 +34,11 @@ (function( $ ){ + const OpenSeadragon = $; // alias back for JSDoc + /** - * @class HTMLDrawer - * @memberof OpenSeadragon + * @class OpenSeadragon.HTMLDrawer + * @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 (
) 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 - * - * @function + * This function is ignored by the HTML Drawer. Implementing it is required by DrawerBase. * @param {Boolean} [imageSmoothingEnabled] - Whether or not the image is * drawn smoothly on the canvas; see imageSmoothingEnabled in * {@link OpenSeadragon.Options} for more explanation. diff --git a/src/webgldrawer.js b/src/webgldrawer.js index a3cda706..32a9e9d2 100644 --- a/src/webgldrawer.js +++ b/src/webgldrawer.js @@ -35,9 +35,10 @@ (function( $ ){ + const OpenSeadragon = $; // alias for JSDoc + /** - * @class WebGLDrawer - * @memberof OpenSeadragon + * @class OpenSeadragon.WebGLDrawer * @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 () 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; - this._firstPass = null; - 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; + // private members + this._destroyed = false; + this._TextureMap = new Map(); + this._TileMap = new Map(); - // Add listeners for events that require modifying the scene or camera - this.viewer.addHandler("tile-ready", ev => this._tileReadyHandler(ev)); - this.viewer.addHandler("image-unloaded", ev => this._imageUnloadedHandler(ev)); + this._gl = null; + this._firstPass = null; + 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 - this.viewer.rejectEventHandler("tile-drawn", "The WebGLDrawer does not raise the tile-drawn event"); - this.viewer.rejectEventHandler("tile-drawing", "The WebGLDrawer does not raise the tile-drawing event"); + // Add listeners for events that require modifying the scene or camera + this.viewer.addHandler("tile-ready", ev => this._tileReadyHandler(ev)); + this.viewer.addHandler("image-unloaded", ev => this._imageUnloadedHandler(ev)); - // 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(); + // Reject listening for the tile-drawing and tile-drawn events, which this drawer does not fire + this.viewer.rejectEventHandler("tile-drawn", "The WebGLDrawer does not raise the tile-drawn event"); + this.viewer.rejectEventHandler("tile-drawing", "The WebGLDrawer does not raise the tile-drawing event"); - 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){