From c5ffd036ca99eb2f8fc7db09ccec3f62435266fb Mon Sep 17 00:00:00 2001 From: Christopher Allen Date: Wed, 29 Sep 2021 01:57:28 +0100 Subject: [PATCH] fix: JSDoc improvments for accessors, etc. (#5567) * fix: Revert removal of documentation for get/set accessors. This partially reverts commit 839cb7b, "fix: infinite loop when using defineProperties (#5549)" * docs: Use @name to attach JSDocs to accessors Reintroduce documentation for deprecated properties where it was removed when converting them to accessors. * docs: Remove duplicate @package declarations * fix: Fix eslint and compiler errors/warnings * fix: Minor JSDoc tweaks to address comments on PR #5567 --- core/blockly.js | 47 ++++++++++++++++++++++++ core/contextmenu.js | 11 +++++- core/events/events.js | 8 ++++ core/events/utils.js | 1 + core/generator.js | 12 ++++-- core/renderers/common/block_rendering.js | 3 -- core/renderers/common/debug.js | 2 - core/tooltip.js | 18 ++++++++- core/widgetdiv.js | 9 ++++- 9 files changed, 97 insertions(+), 14 deletions(-) diff --git a/core/blockly.js b/core/blockly.js index f54b2dc35..71515fc41 100644 --- a/core/blockly.js +++ b/core/blockly.js @@ -198,6 +198,15 @@ exports.VERSION = 'uncompiled'; // Blockly.mainWorkspace, Blockly.prompt and Blockly.selected for backwards // compatibility. Object.defineProperties(exports, { + /** + * Wrapper to window.alert() that app developers may override to + * provide alternatives to the modal browser window. + * @name Blockly.alert + * @type {!function(string, function()=)} + * @deprecated Use Blockly.dialog.alert / .setAlert() instead. + * (September 2021) + * @suppress {checkTypes} + */ alert: { set: function(newAlert) { deprecation.warn('Blockly.alert', 'September 2021', 'September 2022'); @@ -210,6 +219,15 @@ Object.defineProperties(exports, { return dialog.alert; } }, + /** + * Wrapper to window.confirm() that app developers may override to + * provide alternatives to the modal browser window. + * @name Blockly.confirm + * @type {!function(string, function()=)} + * @deprecated Use Blockly.dialog.confirm / .setConfirm() instead. + * (September 2021) + * @suppress {checkTypes} + */ confirm: { set: function(newConfirm) { deprecation.warn('Blockly.confirm', 'September 2021', 'September 2022'); @@ -222,6 +240,15 @@ Object.defineProperties(exports, { return dialog.confirm; } }, + /** + * The main workspace most recently used. + * Set by Blockly.WorkspaceSvg.prototype.markFocused + * @name Blockly.mainWorkspace + * @type {Workspace} + * @deprecated Use Blockly.common.getMainWorkspace() / + * .setMainWorkspace instead. (September 2021) + * @suppress {checkTypes} + */ mainWorkspace: { set: function(x) { deprecation.warn( @@ -235,6 +262,18 @@ Object.defineProperties(exports, { return common.getMainWorkspace(); } }, + /** + * Wrapper to window.prompt() that app developers may override to + * provide alternatives to the modal browser window. Built-in + * browser prompts are often used for better text input experience + * on mobile device. We strongly recommend testing mobile when + * overriding this. + * @name Blockly.prompt + * @type {!function(string, string, function()=)} + * @deprecated Use Blockly.dialog.prompt / .setPrompt() instead. + * (September 2021) + * @suppress {checkTypes} + */ prompt: { set: function(newPrompt) { deprecation.warn('Blockly.prompt', 'September 2021', 'September 2022'); @@ -247,6 +286,14 @@ Object.defineProperties(exports, { return dialog.prompt; } }, + /** + * Currently selected block. + * @name Blockly.selected + * @type {?ICopyable} + * @deprecated Use Blockly.common.getSelected() / .setSelected + * instead. (September 2021) + * @suppress {checkTypes} + */ selected: { get: function() { deprecation.warn( diff --git a/core/contextmenu.js b/core/contextmenu.js index 690e464d6..ceffb728a 100644 --- a/core/contextmenu.js +++ b/core/contextmenu.js @@ -68,8 +68,16 @@ const setCurrentBlock = function(block) { }; exports.setCurrentBlock = setCurrentBlock; -// Ad JS accessors for backwards compatibility. +// Add JS accessors for backwards compatibility. Object.defineProperties(exports, { + /** + * Which block is the context menu attached to? + * @name Blockly.ContextMenu.currentBlock + * @type {Block} + * @deprecated Use Blockly.Tooltip.getCurrentBlock() / + * .setCurrentBlock() instead. (September 2021) + * @suppress {checkTypes} + */ currentBlock: { get: function() { deprecation.warn( @@ -330,7 +338,6 @@ exports.commentDuplicateOption = commentDuplicateOption; * @suppress {strictModuleDepCheck,checkTypes} Suppress checks while workspace * comments are not bundled in. * @alias Blockly.ContextMenu.workspaceCommentOption - * @package */ const workspaceCommentOption = function(ws, e) { const WorkspaceCommentSvg = goog.module.get('Blockly.WorkspaceCommentSvg'); diff --git a/core/events/events.js b/core/events/events.js index 96dd0853e..266e8f35d 100644 --- a/core/events/events.js +++ b/core/events/events.js @@ -123,6 +123,14 @@ exports.setRecordUndo = eventUtils.setRecordUndo; exports.disableOrphans = eventUtils.disableOrphans; Object.defineProperties(exports, { + /** + * Sets whether the next event should be added to the undo stack. + * @name Blockly.Evenents.recordUndo + * @type {boolean} + * @deprecated Use Blockly.Events.getRecordUndo() and + * .setRecordUndo(). (September 2021) + * @suppress {checkTypes} + */ recordUndo: { get: function() { deprecation.warn( diff --git a/core/events/utils.js b/core/events/utils.js index bb6297051..73dc172de 100644 --- a/core/events/utils.js +++ b/core/events/utils.js @@ -31,6 +31,7 @@ const CommentMove = goog.requireType('Blockly.Events.CommentMove'); const Workspace = goog.requireType('Blockly.Workspace'); const idGenerator = goog.require('Blockly.utils.idGenerator'); const registry = goog.require('Blockly.registry'); +/* eslint-disable-next-line no-unused-vars */ const {Block} = goog.requireType('Blockly.Block'); diff --git a/core/generator.js b/core/generator.js index fabbc6984..f98381866 100644 --- a/core/generator.js +++ b/core/generator.js @@ -417,10 +417,16 @@ Generator.prototype.functionNames_; Generator.prototype.nameDB_; Object.defineProperties(Generator.prototype, { + /** + * A database of variable names. + * @name Blockly.Generator.prototype.variableDB_ + * @type {!Names|undefined} + * @protected + * @deprecated 'variableDB_' was renamed to 'nameDB_' (May 2021). + * @suppress {checkTypes} + */ variableDB_: { /** - * Getter. - * @deprecated 'variableDB_' was renamed to 'nameDB_' (May 2021). * @this {Generator} * @return {!Names|undefined} Name database. */ @@ -429,8 +435,6 @@ Object.defineProperties(Generator.prototype, { return this.nameDB_; }, /** - * Setter. - * @deprecated 'variableDB_' was renamed to 'nameDB_' (May 2021). * @this {Generator} * @param {!Names|undefined} nameDb New name database. */ diff --git a/core/renderers/common/block_rendering.js b/core/renderers/common/block_rendering.js index 6e79605a0..6cbf1166a 100644 --- a/core/renderers/common/block_rendering.js +++ b/core/renderers/common/block_rendering.js @@ -92,7 +92,6 @@ exports.unregister = unregister; * Turn on the blocks debugger. * @package * @alias Blockly.blockRendering.startDebugger - * @package */ const startDebugger = function() { deprecation.warn( @@ -106,7 +105,6 @@ exports.startDebugger = startDebugger; * Turn off the blocks debugger. * @package * @alias Blockly.blockRendering.stopDebugger - * @package */ const stopDebugger = function() { deprecation.warn( @@ -125,7 +123,6 @@ exports.stopDebugger = stopDebugger; * Already initialized. * @package * @alias Blockly.blockRendering.init - * @package */ const init = function(name, theme, opt_rendererOverrides) { const rendererClass = registry.getClass(registry.Type.RENDERER, name); diff --git a/core/renderers/common/debug.js b/core/renderers/common/debug.js index 8955d09e1..7527c49a2 100644 --- a/core/renderers/common/debug.js +++ b/core/renderers/common/debug.js @@ -36,7 +36,6 @@ exports.isDebuggerEnabled = isDebuggerEnabled; * Turn on the blocks debugger. * @package * @alias Blockly.blockRendering.debug.startDebugger - * @package */ const startDebugger = function() { useDebugger = true; @@ -47,7 +46,6 @@ exports.startDebugger = startDebugger; * Turn off the blocks debugger. * @package * @alias Blockly.blockRendering.debug.stopDebugger - * @package */ const stopDebugger = function() { useDebugger = false; diff --git a/core/tooltip.js b/core/tooltip.js index 941e502e0..af204f101 100644 --- a/core/tooltip.js +++ b/core/tooltip.js @@ -46,7 +46,6 @@ exports.TipInfo = TipInfo; /** * Is a tooltip currently showing? * @type {boolean} - * @alias Blockly.Tooltip.visible */ let visible = false; @@ -61,6 +60,14 @@ const isVisible = function() { exports.isVisible = isVisible; Object.defineProperties(exports, { + /** + * Is a tooltip currently showing? + * @name Blockly.Tooltip.visible + * @type {boolean} + * @deprecated Use Blockly.Tooltip.isVisible() instead. (September + * 2021) + * @suppress {checkTypes} + */ visible: { get: function() { deprecation.warn( @@ -155,7 +162,6 @@ exports.MARGINS = MARGINS; /** * The HTML container. Set once by createDom. * @type {Element} - * @alias Blockly.Tooltip.DIV */ let DIV = null; @@ -170,6 +176,14 @@ const getDiv = function() { exports.getDiv = getDiv; Object.defineProperties(exports, { + /** + * The HTML container. Set once by createDom. + * @name Blockly.Tooltip.DIV + * @type {Element} + * @deprecated Use Blockly.Tooltip.getDiv() and .setDiv(). + * (September 2021) + * @suppress {checkTypes} + */ DIV: { get: function() { deprecation.warn( diff --git a/core/widgetdiv.js b/core/widgetdiv.js index 67a4f0457..b05133f5b 100644 --- a/core/widgetdiv.js +++ b/core/widgetdiv.js @@ -58,7 +58,6 @@ let themeClassName = ''; /** * The HTML container for popup overlays (e.g. editor widgets). * @type {?Element} - * @alias Blockly.WidgetDiv.DIV */ let DIV; @@ -84,6 +83,14 @@ const testOnly_setDiv = function(newDiv) { exports.testOnly_setDiv = testOnly_setDiv; Object.defineProperties(exports, { + /** + * The HTML container for popup overlays (e.g. editor widgets). + * @name Blockly.WidgetDiv.DIV + * @type {?Element} + * @deprecated Use Blockly.WidgetDiv.getDiv() and .setDiv(). + * (September 2021) + * @suppress {checkTypes} + */ DIV: { get: function() { deprecation.warn(