chore: make inline docs for events informative (#6755)

* chore: make inline docs for events informative

* Notifies the developer -> Notifies listeners

* chore: cleanup from PR comments

* chore: final PR fixes

* chore: format

core/events/events_abstract.ts

@@ -34,7 +34,16 @@ export abstract class Abstract {
 
   /** The workspace identifier for this event. */
   workspaceId?: string = undefined;
+
+  /**
+   * An ID for the group of events this block is associated with.
+   *
+   * Groups define events that should be treated as an single action from the
+   * user's perspective, and should be undone together.
+   */
   group: string;
+
+  /** Whether this event is undoable or not. */
   recordUndo: boolean;
 
   /** Whether or not the event is a UI event. */
@@ -45,14 +54,7 @@ export abstract class Abstract {
 
   /** @alias Blockly.Events.Abstract */
   constructor() {
-    /**
-     * The event group ID for the group this event belongs to. Groups define
-     * events that should be treated as an single action from the user's
-     * perspective, and should be undone together.
-     */
     this.group = eventUtils.getGroup();
-
-    /** Sets whether the event should be added to the undo stack. */
     this.recordUndo = eventUtils.getRecordUndo();
   }
 

core/events/events_block_base.ts

@@ -20,12 +20,14 @@ import {Abstract as AbstractEvent, AbstractEventJson} from './events_abstract.js
 
 
 /**
- * Abstract class for a block event.
+ * Abstract class for any event related to blocks.
  *
  * @alias Blockly.Events.BlockBase
  */
 export class BlockBase extends AbstractEvent {
   override isBlank = true;
+
+  /** The ID of the block associated with this event. */
   blockId?: string;
 
   /**
@@ -38,10 +40,7 @@ export class BlockBase extends AbstractEvent {
 
     if (!opt_block) return;
 
-    /** The block ID for the block this event pertains to */
     this.blockId = opt_block.id;
-
-    /** The workspace identifier for this event. */
     this.workspaceId = opt_block.workspace.id;
   }
 

core/events/events_block_change.ts

@@ -24,15 +24,26 @@ import * as eventUtils from './utils.js';
 
 
 /**
- * Class for a block change event.
+ * Notifies listeners when some element of a block has changed (e.g.
+ * field values, comments, etc).
  *
  * @alias Blockly.Events.BlockChange
  */
 export class BlockChange extends BlockBase {
   override type = eventUtils.BLOCK_CHANGE;
+  /**
+   * The element that changed; one of 'field', 'comment', 'collapsed',
+   * 'disabled', 'inline', or 'mutation'
+   */
   element?: string;
+
+  /** The name of the field that changed, if this is a change to a field. */
   name?: string;
+
+  /** The original value of the element. */
   oldValue: unknown;
+
+  /** The new value of the element. */
   newValue: unknown;
 
   /**

core/events/events_block_create.ts

@@ -24,16 +24,23 @@ import {Workspace} from '../workspace.js';
 
 
 /**
- * Class for a block creation event.
+ * Notifies listeners when a block (or connected stack of blocks) is
+ * created.
  *
  * @alias Blockly.Events.BlockCreate
  */
 export class BlockCreate extends BlockBase {
   override type = eventUtils.BLOCK_CREATE;
+
+  /** The XML representation of the created block(s). */
   xml?: Element|DocumentFragment;
-  ids?: string[];
+
+  /** The JSON respresentation of the created block(s). */
   json?: blocks.State;
 
+  /** All of the IDs of created blocks. */
+  ids?: string[];
+
   /** @param opt_block The created block.  Undefined for a blank event. */
   constructor(opt_block?: Block) {
     super(opt_block);
@@ -50,7 +57,6 @@ export class BlockCreate extends BlockBase {
     this.xml = Xml.blockToDomWithXY(opt_block);
     this.ids = eventUtils.getDescendantIds(opt_block);
 
-    /** JSON representation of the block that was just created. */
     this.json = blocks.save(opt_block, {addCoordinates: true}) as blocks.State;
   }
 

core/events/events_block_delete.ts

@@ -24,15 +24,24 @@ import {Workspace} from '../workspace.js';
 
 
 /**
- * Class for a block deletion event.
+ * Notifies listeners when a block (or connected stack of blocks) is
+ * deleted.
  *
  * @alias Blockly.Events.BlockDelete
  */
 export class BlockDelete extends BlockBase {
+  /** The XML representation of the deleted block(s). */
   oldXml?: Element|DocumentFragment;
-  ids?: string[];
-  wasShadow?: boolean;
+
+  /** The JSON respresentation of the deleted block(s). */
   oldJson?: blocks.State;
+
+  /** All of the IDs of deleted blocks. */
+  ids?: string[];
+
+  /** True if the deleted block was a shadow block, false otherwise. */
+  wasShadow?: boolean;
+
   override type = eventUtils.BLOCK_DELETE;
 
   /** @param opt_block The deleted block.  Undefined for a blank event. */
@@ -53,11 +62,7 @@ export class BlockDelete extends BlockBase {
 
     this.oldXml = Xml.blockToDomWithXY(opt_block);
     this.ids = eventUtils.getDescendantIds(opt_block);
-
-    /** Was the block that was just deleted a shadow? */
     this.wasShadow = opt_block.isShadow();
-
-    /** JSON representation of the block that was just deleted. */
     this.oldJson =
         blocks.save(opt_block, {addCoordinates: true}) as blocks.State;
   }

core/events/events_block_drag.ts

@@ -22,14 +22,23 @@ import {Workspace} from '../workspace.js';
 
 
 /**
- * Class for a block drag event.
+ * Notifies listeners when a block is being manually dragged/dropped.
  *
  * @alias Blockly.Events.BlockDrag
  */
 export class BlockDrag extends UiBase {
+  /** The ID of the top-level block being dragged. */
   blockId?: string;
+
+  /** True if this is the start of a drag, false if this is the end of one. */
   isStart?: boolean;
+
+  /**
+   * A list of all of the blocks (i.e. all descendants of the block associated
+   * with the block ID) being dragged.
+   */
   blocks?: Block[];
+
   override type = eventUtils.BLOCK_DRAG;
 
   /**
@@ -46,11 +55,7 @@ export class BlockDrag extends UiBase {
     if (!opt_block) return;
 
     this.blockId = opt_block.id;
-
-    /** Whether this is the start of a block drag. */
     this.isStart = opt_isStart;
-
-    /** The blocks affected by this drag event. */
     this.blocks = opt_blocks;
   }
 

core/events/events_block_move.ts

@@ -30,18 +30,42 @@ interface BlockLocation {
 }
 
 /**
- * Class for a block move event.  Created before the move.
+ * Notifies listeners when a block is moved. This could be from one
+ * connection to another, or from one location on the workspace to another.
  *
  * @alias Blockly.Events.BlockMove
  */
 export class BlockMove extends BlockBase {
   override type = eventUtils.BLOCK_MOVE;
+
+  /** The ID of the old parent block. Undefined if it was a top-level block. */
   oldParentId?: string;
+
+  /**
+   * The name of the old input. Undefined if it was a top-level block or the
+   * parent's next block.
+   */
   oldInputName?: string;
+
+  /**
+   * The old X and Y workspace coordinates of the block if it was a top level
+   * block. Undefined if it was not a top level block.
+   */
   oldCoordinate?: Coordinate;
 
+  /** The ID of the new parent block. Undefined if it is a top-level block. */
   newParentId?: string;
+
+  /**
+   * The name of the new input. Undefined if it is a top-level block or the
+   * parent's next block.
+   */
   newInputName?: string;
+
+  /**
+   * The new X and Y workspace coordinates of the block if it is a top level
+   * block. Undefined if it is not a top level block.
+   */
   newCoordinate?: Coordinate;
 
   /** @param opt_block The moved block.  Undefined for a blank event. */

core/events/events_bubble_open.ts

@@ -27,9 +27,15 @@ import type {Workspace} from '../workspace.js';
  * @alias Blockly.Events.BubbleOpen
  */
 export class BubbleOpen extends UiBase {
+  /** The ID of the block the bubble is attached to. */
   blockId?: string;
+
+  /** True if the bubble is opening, false if closing. */
   isOpen?: boolean;
+
+  /** The type of bubble; one of 'mutator', 'comment', or 'warning'. */
   bubbleType?: BubbleType;
+
   override type = eventUtils.BUBBLE_OPEN;
 
   /**
@@ -46,11 +52,7 @@ export class BubbleOpen extends UiBase {
     if (!opt_block) return;
 
     this.blockId = opt_block.id;
-
-    /** Whether the bubble is opening (false if closing). */
     this.isOpen = opt_isOpen;
-
-    /** The type of bubble. One of 'mutator', 'comment', or 'warning'. */
     this.bubbleType = opt_bubbleType;
   }
 

core/events/events_click.ts

@@ -23,12 +23,18 @@ import {Workspace} from '../workspace.js';
 
 
 /**
- * Class for a click event.
+ * Notifies listeners that ome blockly element was clicked.
  *
  * @alias Blockly.Events.Click
  */
 export class Click extends UiBase {
+  /** The ID of the block that was clicked, if a block was clicked. */
   blockId?: string;
+
+  /**
+   * The type of element that was clicked; one of 'block', 'workspace',
+   * or 'zoom_controls'.
+   */
   targetType?: ClickTarget;
   override type = eventUtils.CLICK;
 
@@ -51,8 +57,6 @@ export class Click extends UiBase {
     super(workspaceId);
 
     this.blockId = opt_block ? opt_block.id : undefined;
-
-    /** The type of element targeted by this click event. */
     this.targetType = opt_targetType;
   }
 

core/events/events_comment_base.ts

@@ -31,6 +31,8 @@ import type {Workspace} from '../workspace.js';
  */
 export class CommentBase extends AbstractEvent {
   override isBlank = true;
+
+  /** The ID of the comment that this event references. */
   commentId?: string;
 
   /**
@@ -44,20 +46,9 @@ export class CommentBase extends AbstractEvent {
 
     if (!opt_comment) return;
 
-    /** The ID of the comment this event pertains to. */
     this.commentId = opt_comment.id;
-
-    /** The workspace identifier for this event. */
     this.workspaceId = opt_comment.workspace.id;
-
-    /**
-     * The event group ID for the group this event belongs to. Groups define
-     * events that should be treated as an single action from the user's
-     * perspective, and should be undone together.
-     */
     this.group = eventUtils.getGroup();
-
-    /** Sets whether the event should be added to the undo stack. */
     this.recordUndo = eventUtils.getRecordUndo();
   }
 

core/events/events_comment_change.ts

@@ -22,13 +22,18 @@ import type {Workspace} from '../workspace.js';
 
 
 /**
- * Class for a comment change event.
+ * Notifies listeners that the contents of a workspace comment has changed.
  *
  * @alias Blockly.Events.CommentChange
  */
 export class CommentChange extends CommentBase {
   override type = eventUtils.COMMENT_CHANGE;
+
+  // TODO(#6774): We should remove underscores.
+  /** The previous contents of the comment. */
   oldContents_?: string;
+
+  /** The new contents of the comment. */
   newContents_?: string;
 
   /**

core/events/events_comment_create.ts

@@ -23,13 +23,14 @@ import type {Workspace} from '../workspace.js';
 
 
 /**
- * Class for a comment creation event.
+ * Notifies listeners that a workspace comment was created.
  *
  * @alias Blockly.Events.CommentCreate
  */
 export class CommentCreate extends CommentBase {
   override type = eventUtils.COMMENT_CREATE;
 
+  /** The XML representation of the created workspace comment. */
   xml?: Element|DocumentFragment;
 
   /**

core/events/events_comment_delete.ts

@@ -22,12 +22,14 @@ import type {Workspace} from '../workspace.js';
 
 
 /**
- * Class for a comment deletion event.
+ * Notifies listeners that a workspace comment has been deleted.
  *
  * @alias Blockly.Events.CommentDelete
  */
 export class CommentDelete extends CommentBase {
   override type = eventUtils.COMMENT_DELETE;
+
+  /** The XML representation of the deleted workspace comment. */
   xml?: Element;
 
   /**

core/events/events_comment_move.ts

@@ -23,15 +23,21 @@ import type {Workspace} from '../workspace.js';
 
 
 /**
- * Class for a comment move event.  Created before the move.
+ * Notifies listeners that a workspace comment has moved.
  *
  * @alias Blockly.Events.CommentMove
  */
 export class CommentMove extends CommentBase {
   override type = eventUtils.COMMENT_MOVE;
+
+  /** The comment that is being moved. */
   comment_?: WorkspaceComment;
+
+  // TODO(#6774): We should remove underscores.
+  /** The location of the comment before the move, in workspace coordinates. */
   oldCoordinate_?: Coordinate;
-  /** The location after the move, in workspace coordinates. */
+
+  /** The location of the comment after the move, in workspace coordinates. */
   newCoordinate_?: Coordinate;
 
   /**
@@ -45,12 +51,7 @@ export class CommentMove extends CommentBase {
       return;  // Blank event to be populated by fromJson.
     }
 
-    /**
-     * The comment that is being moved.
-     */
     this.comment_ = opt_comment;
-
-    /** The location before the move, in workspace coordinates. */
     this.oldCoordinate_ = opt_comment.getXY();
   }
 

core/events/events_marker_move.ts

@@ -24,15 +24,28 @@ import * as eventUtils from './utils.js';
 
 
 /**
- * Class for a marker move event.
+ * Notifies listeners that a marker (used for keyboard navigation) has
+ * moved.
  *
  * @alias Blockly.Events.MarkerMove
  */
 export class MarkerMove extends UiBase {
+  /** The ID of the block the marker is now on, if any. */
   blockId?: string;
+
+  /** The old node the marker used to be on, if any. */
   oldNode?: ASTNode;
+
+  /** The new node the marker is now on. */
   newNode?: ASTNode;
+
+  /**
+   * True if this is a cursor event, false otherwise.
+   * For information about cursors vs markers see {@link
+   * https://blocklycodelabs.dev/codelabs/keyboard-navigation/index.html?index=..%2F..index#1}.
+   */
   isCursor?: boolean;
+
   override type = eventUtils.MARKER_MOVE;
 
   /**
@@ -54,16 +67,9 @@ export class MarkerMove extends UiBase {
     }
     super(workspaceId);
 
-    /** The block identifier for this event. */
     this.blockId = opt_block?.id;
-
-    /** The old node the marker used to be on. */
     this.oldNode = opt_oldNode || undefined;
-
-    /** The new node the  marker is now on. */
     this.newNode = opt_newNode;
-
-    /** Whether this is a cursor event. */
     this.isCursor = isCursor;
   }
 

core/events/events_procedure_base.ts

@@ -15,6 +15,10 @@ import type {Workspace} from '../workspace.js';
 export abstract class ProcedureBase extends AbstractEvent {
   isBlank = false;
 
+  /**
+   * @param workspace The workspace the procedure model exists in.
+   * @param model The procedure model associated with this event.
+   */
   constructor(workspace: Workspace, public readonly model: IProcedureModel) {
     super();
     this.workspaceId = workspace.id;

core/events/events_procedure_change_return.ts

@@ -14,7 +14,7 @@ import * as eventUtils from './utils.js';
 
 
 /**
- * Represents a procedure's return type/status changing.
+ * Notifies listeners that a procedure's return type/status has changed.
  */
 export class ProcedureChangeReturn extends ProcedureBase {
   /** A string used to check the type of the event. */

core/events/events_procedure_create.ts

@@ -15,7 +15,7 @@ import * as eventUtils from './utils.js';
 
 
 /**
- * Represents a procedure data model being created.
+ * Notifies listeners that a procedure data model has been created.
  */
 export class ProcedureCreate extends ProcedureBase {
   /** A string used to check the type of the event. */

core/events/events_procedure_delete.ts

@@ -15,7 +15,7 @@ import * as eventUtils from './utils.js';
 
 
 /**
- * Represents a procedure data model being deleted.
+ * Notifies listeners that a procedure data model has been deleted.
  */
 export class ProcedureDelete extends ProcedureBase {
   /** A string used to check the type of the event. */

core/events/events_procedure_enable.ts

@@ -13,7 +13,8 @@ import {ProcedureBase, ProcedureBaseJson} from './events_procedure_base.js';
 import * as eventUtils from './utils.js';
 
 /**
- * Represents a procedure data model being enabled or disabled.
+ * Notifies listeners that the procedure data model has been enabled or
+ * disabled.
  */
 export class ProcedureEnable extends ProcedureBase {
   /** A string used to check the type of the event. */

core/events/events_procedure_parameter_base.ts

@@ -16,6 +16,11 @@ import type {Workspace} from '../workspace.js';
  * The base event for an event associated with a procedure parameter.
  */
 export abstract class ProcedureParameterBase extends ProcedureBase {
+  /**
+   * @param workspace The workspace the parameter model exists in.
+   * @param model The procedure model the parameter model belongs to.
+   * @param parameter The parameter model associated with this event.
+   */
   constructor(
       workspace: Workspace, model: IProcedureModel,
       public readonly parameter: IParameterModel) {

core/events/events_procedure_parameter_create.ts

@@ -16,7 +16,7 @@ import * as eventUtils from './utils.js';
 
 
 /**
- * Represents a parameter being added to a procedure.
+ * Notifies listeners that a parameter has been added to a procedure model.
  */
 export class ProcedureParameterCreate extends ProcedureParameterBase {
   /** A string used to check the type of the event. */

core/events/events_procedure_parameter_delete.ts

@@ -14,7 +14,7 @@ import {ProcedureParameterBase, ProcedureParameterBaseJson} from './events_proce
 import * as eventUtils from './utils.js';
 
 /**
- * Represents a parameter being removed from a procedure.
+ * Notifies listeners that a parameter has been removed from a procedure.
  */
 export class ProcedureParameterDelete extends ProcedureParameterBase {
   /** A string used to check the type of the event. */

core/events/events_procedure_parameter_rename.ts

@@ -13,13 +13,16 @@ import {ProcedureParameterBase, ProcedureParameterBaseJson} from './events_proce
 import * as eventUtils from './utils.js';
 
 /**
- * Represents a parameter of a procedure being renamed.
+ * Notifies listeners that a procedure parameter was renamed.
  */
 export class ProcedureParameterRename extends ProcedureParameterBase {
   /** A string used to check the type of the event. */
   type = eventUtils.PROCEDURE_PARAMETER_RENAME;
+
+  /** The new name of the procedure parameter. */
   private readonly newName: string;
 
+  /** @param oldName The old name of the procedure parameter. */
   constructor(
       workspace: Workspace, procedure: IProcedureModel,
       parameter: IParameterModel, public readonly oldName: string) {

core/events/events_procedure_rename.ts

@@ -11,14 +11,14 @@ import type {Workspace} from '../workspace.js';
 import {ProcedureBase, ProcedureBaseJson} from './events_procedure_base.js';
 import * as eventUtils from './utils.js';
 
-/**
- * Represents a procedure being renamed.
- */
+/** Notifies listeners that a procedure model has been renamed. */
 export class ProcedureRename extends ProcedureBase {
   /** A string used to check the type of the event. */
   type = eventUtils.PROCEDURE_RENAME;
+
   private newName: string;
 
+  /** @param oldName The old name of the procedure model. */
   constructor(
       workspace: Workspace, model: IProcedureModel,
       public readonly oldName: string) {

core/events/events_selected.ts

@@ -23,12 +23,20 @@ import type {Workspace} from '../workspace.js';
 
 /**
  * Class for a selected event.
+ * Notifies listeners that a new element has been selected.
  *
  * @alias Blockly.Events.Selected
  */
 export class Selected extends UiBase {
+  /** The id of the last selected selectable element. */
   oldElementId?: string;
+
+  /**
+   * The id of the newly selected selectable element,
+   * or undefined if unselected.
+   */
   newElementId?: string;
+
   override type = eventUtils.SELECTED;
 
   /**
@@ -44,10 +52,7 @@ export class Selected extends UiBase {
       opt_workspaceId?: string) {
     super(opt_workspaceId);
 
-    /** The id of the last selected element. */
     this.oldElementId = opt_oldElementId ?? undefined;
-
-    /** The id of the selected element. */
     this.newElementId = opt_newElementId ?? undefined;
   }
 

core/events/events_theme_change.ts

@@ -21,12 +21,14 @@ import type {Workspace} from '../workspace.js';
 
 
 /**
- * Class for a theme change event.
+ * Notifies listeners that the workspace theme has changed.
  *
  * @alias Blockly.Events.ThemeChange
  */
 export class ThemeChange extends UiBase {
+  /** The name of the new theme that has been set. */
   themeName?: string;
+
   override type = eventUtils.THEME_CHANGE;
 
   /**
@@ -36,8 +38,6 @@ export class ThemeChange extends UiBase {
    */
   constructor(opt_themeName?: string, opt_workspaceId?: string) {
     super(opt_workspaceId);
-
-    /** The theme name. */
     this.themeName = opt_themeName;
   }
 

core/events/events_toolbox_item_select.ts

@@ -21,13 +21,17 @@ import type {Workspace} from '../workspace.js';
 
 
 /**
- * Class for a toolbox item select event.
+ * Notifies listeners that a toolbox item has been selected.
  *
  * @alias Blockly.Events.ToolboxItemSelect
  */
 export class ToolboxItemSelect extends UiBase {
+  /** The previously selected toolbox item. */
   oldItem?: string;
+
+  /** The newly selected toolbox item. */
   newItem?: string;
+
   override type = eventUtils.TOOLBOX_ITEM_SELECT;
 
   /**
@@ -42,11 +46,7 @@ export class ToolboxItemSelect extends UiBase {
       opt_oldItem?: string|null, opt_newItem?: string|null,
       opt_workspaceId?: string) {
     super(opt_workspaceId);
-
-    /** The previously selected toolbox item. */
     this.oldItem = opt_oldItem ?? undefined;
-
-    /** The newly selected toolbox item. */
     this.newItem = opt_newItem ?? undefined;
   }
 

core/events/events_trashcan_open.ts

@@ -22,11 +22,15 @@ import type {Workspace} from '../workspace.js';
 
 
 /**
- * Class for a trashcan open event.
+ * Notifies listeners when the trashcan is opening or closing.
  *
  * @alias Blockly.Events.TrashcanOpen
  */
 export class TrashcanOpen extends UiBase {
+  /**
+   * True if the trashcan is currently opening (previously closed).
+   * False if it is currently closing (previously open).
+   */
   isOpen?: boolean;
   override type = eventUtils.TRASHCAN_OPEN;
 
@@ -38,8 +42,6 @@ export class TrashcanOpen extends UiBase {
    */
   constructor(opt_isOpen?: boolean, opt_workspaceId?: string) {
     super(opt_workspaceId);
-
-    /** Whether the trashcan flyout is opening (false if closing). */
     this.isOpen = opt_isOpen;
   }
 

core/events/events_var_base.ts

@@ -26,6 +26,7 @@ import type {Workspace} from '../workspace.js';
  */
 export class VarBase extends AbstractEvent {
   override isBlank = true;
+  /** The ID of the variable this event references. */
   varId?: string;
 
   /**
@@ -37,10 +38,7 @@ export class VarBase extends AbstractEvent {
     this.isBlank = typeof opt_variable === 'undefined';
     if (!opt_variable) return;
 
-    /** The variable id for the variable this event pertains to. */
     this.varId = opt_variable.getId();
-
-    /** The workspace identifier for this event. */
     this.workspaceId = opt_variable.workspace.id;
   }
 

core/events/events_var_create.ts

@@ -22,13 +22,17 @@ import type {Workspace} from '../workspace.js';
 
 
 /**
- * Class for a variable creation event.
+ * Notifies listeners that a variable model has been created.
  *
  * @alias Blockly.Events.VarCreate
  */
 export class VarCreate extends VarBase {
   override type = eventUtils.VAR_CREATE;
+
+  /** The type of the variable that was created. */
   varType?: string;
+
+  /** The name of the variable that was created. */
   varName?: string;
 
   /**

core/events/events_var_delete.ts

@@ -4,11 +4,6 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-/**
- * Classes for all types of variable events.
- *
- * @class
- */
 import * as goog from '../../closure/goog/goog.js';
 goog.declareModuleId('Blockly.Events.VarDelete');
 
@@ -22,13 +17,15 @@ import type {Workspace} from '../workspace.js';
 
 
 /**
- * Class for a variable deletion event.
+ * Notifies listeners that a variable model has been deleted.
  *
- * @alias Blockly.Events.VarDelete
+ * @class
  */
 export class VarDelete extends VarBase {
   override type = eventUtils.VAR_DELETE;
+  /** The type of the variable that was deleted. */
   varType?: string;
+  /** The name of the variable that was deleted. */
   varName?: string;
 
   /**

core/events/events_var_rename.ts

@@ -4,11 +4,6 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-/**
- * Class for a variable rename event.
- *
- * @class
- */
 import * as goog from '../../closure/goog/goog.js';
 goog.declareModuleId('Blockly.Events.VarRename');
 
@@ -22,13 +17,17 @@ import type {Workspace} from '../workspace.js';
 
 
 /**
- * Class for a variable rename event.
+ * Notifies listeners that a variable model was renamed.
  *
- * @alias Blockly.Events.VarRename
+ * @class
  */
 export class VarRename extends VarBase {
   override type = eventUtils.VAR_RENAME;
+
+  /** The previous name of the variable. */
   oldName?: string;
+
+  /** The new name of the variable. */
   newName?: string;
 
   /**

core/events/events_viewport.ts

@@ -21,15 +21,32 @@ import type {Workspace} from '../workspace.js';
 
 
 /**
- * Class for a viewport change event.
+ * Notifies listeners that the workspace surface's position or scale has
+ * changed.
+ *
+ * Does not notify when the workspace itself resizes.
  *
  * @alias Blockly.Events.ViewportChange
  */
 export class ViewportChange extends UiBase {
+  /**
+   * Top edge of the visible portion of the workspace, relative to the
+   * workspace origin.
+   */
   viewTop?: number;
+
+  /**
+   * The left edge of the visible portion of the workspace, relative to
+   * the workspace origin.
+   */
   viewLeft?: number;
+
+  /** The scale of the workpace. */
   scale?: number;
+
+  /** The previous scale of the workspace. */
   oldScale?: number;
+
   override type = eventUtils.VIEWPORT_CHANGE;
 
   /**
@@ -48,22 +65,9 @@ export class ViewportChange extends UiBase {
       opt_workspaceId?: string, opt_oldScale?: number) {
     super(opt_workspaceId);
 
-    /**
-     * Top-edge of the visible portion of the workspace, relative to the
-     * workspace origin.
-     */
     this.viewTop = opt_top;
-
-    /**
-     * Left-edge of the visible portion of the workspace, relative to the
-     * workspace origin.
-     */
     this.viewLeft = opt_left;
-
-    /** The scale of the workspace. */
     this.scale = opt_scale;
-
-    /** The old scale of the workspace. */
     this.oldScale = opt_oldScale;
   }
 

core/events/workspace_events.ts

@@ -19,10 +19,8 @@ import * as eventUtils from './utils.js';
 
 
 /**
- * Class for a finished loading event.
- * Used to notify the developer when the workspace has finished loading (i.e
- * domToWorkspace).
- * Finished loading events do not record undo or redo.
+ * Notifies listeners when the workspace has finished deserializing from
+ * JSON/XML.
  *
  * @alias Blockly.Events.FinishedLoading
  */
@@ -37,12 +35,10 @@ export class FinishedLoading extends AbstractEvent {
    */
   constructor(opt_workspace?: Workspace) {
     super();
-    /** Whether or not the event is blank (to be populated by fromJson). */
     this.isBlank = !!opt_workspace;
 
     if (!opt_workspace) return;
 
-    /** The workspace identifier for this event. */
     this.workspaceId = opt_workspace.id;
   }