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
2026-01-10 18:37:09 +01:00 · 2021-09-29 01:57:28 +01:00
parent 49bc2b1ae4
commit c5ffd036ca
9 changed files with 97 additions and 14 deletions
--- 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(
--- 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');
--- 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(
--- 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');


--- 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.
     */
--- 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);
--- 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;
--- 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(
--- 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(