From d6d8656a454e96e03433b454d62f5a4566a9beeb Mon Sep 17 00:00:00 2001 From: Maribeth Bottorff Date: Tue, 16 Aug 2022 16:13:39 -0700 Subject: [PATCH] chore: change return to returns and add some newlines --- core/block.ts | 203 +++++++++++++----- core/block_drag_surface.ts | 21 +- core/block_dragger.ts | 28 ++- core/block_svg.ts | 110 ++++++++-- core/blockly_options.ts | 2 + core/blocks.ts | 2 + core/bubble.ts | 54 ++++- core/clipboard.ts | 12 +- core/common.ts | 39 +++- core/component_manager.ts | 18 +- core/connection.ts | 73 +++++-- core/connection_checker.ts | 23 +- core/connection_type.ts | 2 + core/constants.ts | 3 + core/contextmenu_items.ts | 25 ++- core/contextmenu_registry.ts | 9 +- core/delete_area.ts | 6 +- core/dialog.ts | 10 + core/drag_target.ts | 12 +- core/dropdowndiv.ts | 53 +++-- core/events/events_block_drag.ts | 6 +- core/events/events_theme_change.ts | 6 +- core/events/events_toolbox_item_select.ts | 6 +- core/events/utils.ts | 59 ++++- core/extensions.ts | 51 ++++- core/field_angle.ts | 21 +- core/field_colour.ts | 28 ++- core/field_image.ts | 19 +- core/field_label.ts | 10 +- core/field_multilineinput.ts | 27 ++- core/field_number.ts | 28 ++- core/field_textinput.ts | 34 ++- core/field_variable.ts | 48 +++-- core/flyout_button.ts | 17 +- core/flyout_horizontal.ts | 20 +- core/flyout_metrics_manager.ts | 5 +- core/generator.ts | 50 +++-- core/input.ts | 35 ++- core/input_types.ts | 2 + core/insertion_marker_manager.ts | 35 ++- core/keyboard_nav/ast_node.ts | 81 ++++--- core/keyboard_nav/basic_cursor.ts | 29 ++- core/keyboard_nav/cursor.ts | 14 +- core/keyboard_nav/marker.ts | 11 +- core/keyboard_nav/tab_navigate_cursor.ts | 5 +- core/marker_manager.ts | 15 +- core/menu.ts | 24 ++- core/menuitem.ts | 25 ++- core/mutator.ts | 28 ++- core/names.ts | 24 ++- core/positionable_helpers.ts | 14 +- core/procedures.ts | 37 +++- core/registry.ts | 27 ++- core/rendered_connection.ts | 35 ++- core/renderers/common/block_rendering.ts | 11 +- core/renderers/common/constants.ts | 70 ++++-- core/renderers/common/debug.ts | 6 +- core/renderers/common/debugger.ts | 13 ++ core/renderers/common/drawer.ts | 12 ++ core/renderers/common/i_path_object.ts | 15 ++ core/renderers/common/info.ts | 33 ++- core/renderers/common/marker_svg.ts | 41 +++- core/renderers/common/path_object.ts | 20 ++ core/renderers/common/renderer.ts | 41 +++- core/renderers/geras/constants.ts | 2 + core/renderers/geras/drawer.ts | 2 + core/renderers/geras/geras.ts | 3 +- core/renderers/geras/highlight_constants.ts | 16 +- core/renderers/geras/highlighter.ts | 13 +- core/renderers/geras/info.ts | 5 +- .../geras/measurables/inline_input.ts | 2 + .../geras/measurables/statement_input.ts | 2 + core/renderers/geras/path_object.ts | 4 + core/renderers/geras/renderer.ts | 20 +- core/renderers/measurables/base.ts | 2 + core/renderers/measurables/bottom_row.ts | 11 +- core/renderers/measurables/connection.ts | 2 + .../measurables/external_value_input.ts | 2 + core/renderers/measurables/field.ts | 2 + core/renderers/measurables/hat.ts | 2 + core/renderers/measurables/icon.ts | 3 + core/renderers/measurables/in_row_spacer.ts | 2 + core/renderers/measurables/inline_input.ts | 2 + .../renderers/measurables/input_connection.ts | 2 + core/renderers/measurables/input_row.ts | 4 + core/renderers/measurables/jagged_edge.ts | 2 + core/renderers/measurables/next_connection.ts | 2 + .../measurables/output_connection.ts | 2 + .../measurables/previous_connection.ts | 2 + core/renderers/measurables/round_corner.ts | 2 + core/renderers/measurables/row.ts | 32 ++- core/renderers/measurables/spacer_row.ts | 2 + core/renderers/measurables/square_corner.ts | 2 + core/renderers/measurables/statement_input.ts | 2 + core/renderers/measurables/top_row.ts | 9 +- core/renderers/measurables/types.ts | 79 ++++--- core/renderers/minimalist/constants.ts | 2 + core/renderers/minimalist/drawer.ts | 2 + core/renderers/minimalist/info.ts | 5 +- core/renderers/minimalist/minimalist.ts | 3 +- core/renderers/minimalist/renderer.ts | 11 +- core/renderers/thrasos/info.ts | 5 +- core/renderers/thrasos/renderer.ts | 5 +- core/renderers/thrasos/thrasos.ts | 3 +- core/renderers/zelos/constants.ts | 27 ++- core/renderers/zelos/drawer.ts | 3 + core/renderers/zelos/info.ts | 8 +- core/renderers/zelos/marker_svg.ts | 5 + .../renderers/zelos/measurables/bottom_row.ts | 14 +- core/renderers/zelos/measurables/inputs.ts | 2 + .../zelos/measurables/row_elements.ts | 2 + core/renderers/zelos/measurables/top_row.ts | 14 +- core/renderers/zelos/path_object.ts | 9 +- core/renderers/zelos/renderer.ts | 20 +- core/renderers/zelos/zelos.ts | 3 +- core/scrollbar.ts | 42 +++- core/scrollbar_pair.ts | 19 +- core/serialization/blocks.ts | 53 ++++- core/serialization/exceptions.ts | 5 + core/serialization/priorities.ts | 3 + core/serialization/registry.ts | 3 + core/serialization/variables.ts | 8 +- core/serialization/workspaces.ts | 6 +- core/shortcut_items.ts | 10 + core/shortcut_registry.ts | 34 ++- core/sprites.ts | 1 + core/theme/classic.ts | 2 + core/theme/zelos.ts | 2 + core/theme_manager.ts | 11 +- core/toolbox/category.ts | 57 +++-- core/toolbox/collapsible_category.ts | 13 +- core/toolbox/separator.ts | 5 +- core/toolbox/toolbox.ts | 92 ++++++-- core/toolbox/toolbox_item.ts | 24 ++- core/tooltip.ts | 30 ++- core/touch.ts | 24 ++- core/touch_gesture.ts | 18 +- core/trashcan.ts | 34 ++- core/utils.ts | 54 +++-- core/utils/aria.ts | 4 + core/utils/array.ts | 3 +- core/utils/colour.ts | 29 ++- core/utils/coordinate.ts | 26 ++- core/utils/deprecation.ts | 2 + core/utils/dom.ts | 40 +++- core/utils/idgenerator.ts | 10 +- core/utils/keycodes.ts | 1 + core/utils/math.ts | 10 +- core/utils/metrics.ts | 1 + core/utils/object.ts | 9 +- core/utils/parsing.ts | 15 +- core/utils/rect.ts | 7 +- core/utils/size.ts | 5 +- core/utils/string.ts | 31 ++- core/utils/style.ts | 28 ++- core/utils/svg.ts | 5 +- core/utils/svg_math.ts | 22 +- core/utils/svg_paths.ts | 25 ++- core/utils/toolbox.ts | 41 +++- core/utils/useragent.ts | 4 +- core/utils/xml.ts | 18 +- core/variable_map.ts | 33 ++- core/variables.ts | 53 +++-- core/variables_dynamic.ts | 19 +- core/warning.ts | 8 +- core/widgetdiv.ts | 20 +- core/workspace.ts | 108 +++++++--- core/workspace_comment_svg.ts | 61 +++++- core/workspace_drag_surface_svg.ts | 30 +-- core/workspace_dragger.ts | 6 + core/xml.ts | 61 ++++-- core/zoom_controls.ts | 14 +- 172 files changed, 2752 insertions(+), 772 deletions(-) diff --git a/core/block.ts b/core/block.ts index ec13826ac..10f384352 100644 --- a/core/block.ts +++ b/core/block.ts @@ -6,6 +6,7 @@ /** * The class representing one block. + * * @class */ import * as goog from '../closure/goog/goog.js'; @@ -49,6 +50,7 @@ import type {Workspace} from './workspace.js'; /** * Class for one block. * Not normally called directly, workspace.newBlock() is preferred. + * * @unrestricted * @alias Blockly.Block */ @@ -74,6 +76,7 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Has this block been disposed of? + * * @internal */ disposed = false; @@ -180,6 +183,7 @@ export class Block implements IASTNodeLocation, IDeletable { /** * A string representing the comment attached to this block. + * * @deprecated August 2019. Use getCommentText instead. */ comment: string|Comment|null = null; @@ -210,6 +214,7 @@ export class Block implements IASTNodeLocation, IDeletable { /** * A count of statement inputs on the block. + * * @internal */ statementInputCount = 0; @@ -305,6 +310,7 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Dispose of this block. + * * @param healStack If true, then try to heal any gap by connecting the next * statement with the previous statement. Otherwise, dispose of all * children of this block. @@ -376,6 +382,7 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Unplug this block from its superior block. If this block is a statement, * optionally reconnect the block underneath with the block on top. + * * @param opt_healStack Disconnect child statement and reconnect stack. * Defaults to false. */ @@ -391,6 +398,7 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Unplug this block's output from an input on another block. Optionally * reconnect the block's parent to the only child block, if possible. + * * @param opt_healStack Disconnect right-side block and connect to left-side * block. Defaults to false. */ @@ -434,7 +442,7 @@ export class Block implements IASTNodeLocation, IDeletable { * Since only one block can be displaced and attached to the insertion marker * this should only ever return one connection. * - * @return The connection on the value input, or null. + * @returns The connection on the value input, or null. */ private getOnlyValueConnection_(): Connection|null { let connection = null; @@ -455,6 +463,7 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Unplug this statement block from its superior block. Optionally reconnect * the block underneath with the block on top. + * * @param opt_healStack Disconnect child statement and reconnect stack. * Defaults to false. */ @@ -482,8 +491,9 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Returns all connections originating from this block. + * * @param _all If true, return all connections even hidden ones. - * @return Array of connections. + * @returns Array of connections. * @internal */ getConnections_(_all: boolean): Connection[] { @@ -508,10 +518,11 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Walks down a stack of blocks and finds the last next connection on the * stack. + * * @param ignoreShadows If true,the last connection on a non-shadow block will * be returned. If false, this will follow shadows to find the last * connection. - * @return The last next connection on the stack, or null. + * @returns The last next connection on the stack, or null. * @internal */ lastConnectionInStack(ignoreShadows: boolean): Connection|null { @@ -538,7 +549,8 @@ export class Block implements IASTNodeLocation, IDeletable { * parent block is either the block connected to the previous connection (for * a statement block) or the block connected to the output connection (for a * value block). - * @return The block (if any) that holds the current block. + * + * @returns The block (if any) that holds the current block. */ getParent(): this|null { return this.parentBlock_; @@ -546,8 +558,9 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Return the input that connects to the specified block. + * * @param block A block connected to an input on this block. - * @return The input (if any) that connects to the specified block. + * @returns The input (if any) that connects to the specified block. */ getInputWithBlock(block: Block): Input|null { for (let i = 0, input; input = this.inputList[i]; i++) { @@ -563,7 +576,8 @@ export class Block implements IASTNodeLocation, IDeletable { * block has no surrounding block. A parent block might just be the previous * statement, whereas the surrounding block is an if statement, while loop, * etc. - * @return The block (if any) that surrounds the current block. + * + * @returns The block (if any) that surrounds the current block. */ getSurroundParent(): this|null { let block = this; @@ -584,7 +598,8 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Return the next statement block directly connected to this block. - * @return The next statement block or null. + * + * @returns The next statement block or null. */ getNextBlock(): Block|null { return this.nextConnection && this.nextConnection.targetBlock(); @@ -592,7 +607,8 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Returns the block connected to the previous connection. - * @return The previous statement block or null. + * + * @returns The previous statement block or null. */ getPreviousBlock(): Block|null { return this.previousConnection && this.previousConnection.targetBlock(); @@ -601,7 +617,8 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Return the connection on the first statement input on this block, or null * if there are none. - * @return The first statement connection or null. + * + * @returns The first statement connection or null. * @internal */ getFirstStatementConnection(): Connection|null { @@ -617,7 +634,8 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Return the top-most block in this block's tree. * This will return itself if this block is at the top level. - * @return The root block. + * + * @returns The root block. */ getRootBlock(): this { let rootBlock: this; @@ -633,7 +651,8 @@ export class Block implements IASTNodeLocation, IDeletable { * Walk up from the given block up through the stack of blocks to find * the top block of the sub stack. If we are nested in a statement input only * find the top-most nested block. Do not go all the way to the root block. - * @return The top block in a stack. + * + * @returns The top block in a stack. * @internal */ getTopStackBlock(): this { @@ -653,8 +672,9 @@ export class Block implements IASTNodeLocation, IDeletable { * Includes value and statement inputs, as well as any following statement. * Excludes any connection on an output tab or any preceding statement. * Blocks are optionally sorted by position; top to bottom. + * * @param ordered Sort the list if true. - * @return Array of blocks. + * @returns Array of blocks. */ getChildren(ordered: boolean): Block[] { if (!ordered) { @@ -678,6 +698,7 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Set parent of this block to be a new block or null. + * * @param newParent New parent block. * @internal */ @@ -730,8 +751,9 @@ export class Block implements IASTNodeLocation, IDeletable { * Includes value and statement inputs, as well as any following statements. * Excludes any connection on an output tab or any preceding statements. * Blocks are optionally sorted by position; top to bottom. + * * @param ordered Sort the list if true. - * @return Flattened array of blocks. + * @returns Flattened array of blocks. */ getDescendants(ordered: boolean): this[] { const blocks = [this]; @@ -746,7 +768,8 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Get whether this block is deletable or not. - * @return True if deletable. + * + * @returns True if deletable. */ isDeletable(): boolean { return this.deletable_ && !this.isShadow_ && !this.disposed && @@ -755,6 +778,7 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Set whether this block is deletable or not. + * * @param deletable True if deletable. */ setDeletable(deletable: boolean) { @@ -763,7 +787,8 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Get whether this block is movable or not. - * @return True if movable. + * + * @returns True if movable. */ isMovable(): boolean { return this.movable_ && !this.isShadow_ && !this.disposed && @@ -772,6 +797,7 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Set whether this block is movable or not. + * * @param movable True if movable. */ setMovable(movable: boolean) { @@ -783,7 +809,8 @@ export class Block implements IASTNodeLocation, IDeletable { * descendants will put this block over the workspace's capacity this block is * not duplicatable. If duplicating this block and descendants will put any * type over their maxInstances this block is not duplicatable. - * @return True if duplicatable. + * + * @returns True if duplicatable. */ isDuplicatable(): boolean { if (!this.workspace.hasBlockLimits()) { @@ -795,7 +822,8 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Get whether this block is a shadow block or not. - * @return True if a shadow. + * + * @returns True if a shadow. */ isShadow(): boolean { return this.isShadow_; @@ -803,6 +831,7 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Set whether this block is a shadow block or not. + * * @param shadow True if a shadow. * @internal */ @@ -812,7 +841,8 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Get whether this block is an insertion marker block or not. - * @return True if an insertion marker. + * + * @returns True if an insertion marker. */ isInsertionMarker(): boolean { return this.isInsertionMarker_; @@ -821,6 +851,7 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Set whether this block is an insertion marker block or not. * Once set this cannot be unset. + * * @param insertionMarker True if an insertion marker. * @internal */ @@ -830,7 +861,8 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Get whether this block is editable or not. - * @return True if editable. + * + * @returns True if editable. */ isEditable(): boolean { return this.editable_ && !this.disposed && !this.workspace.options.readOnly; @@ -838,6 +870,7 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Set whether this block is editable or not. + * * @param editable True if editable. */ setEditable(editable: boolean) { @@ -851,7 +884,8 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Returns if this block has been disposed of / deleted. - * @return True if this block has been disposed of / deleted. + * + * @returns True if this block has been disposed of / deleted. */ isDisposed(): boolean { return this.disposed; @@ -861,9 +895,10 @@ export class Block implements IASTNodeLocation, IDeletable { * Find the connection on this block that corresponds to the given connection * on the other block. * Used to match connections between a block and its insertion marker. + * * @param otherBlock The other block to match against. * @param conn The other connection to match. - * @return The matching connection on this block, or null. + * @returns The matching connection on this block, or null. * @internal */ getMatchingConnection(otherBlock: Block, conn: Connection): Connection|null { @@ -882,6 +917,7 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Set the URL of this block's help page. + * * @param url URL string for block help, or function that returns a URL. Null * for no help. */ @@ -891,6 +927,7 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Sets the tooltip for this block. + * * @param newTip The text for the tooltip, a function that returns the text * for the tooltip, or a parent object whose tooltip will be used. To not * display a tooltip pass the empty string. @@ -901,7 +938,8 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Returns the tooltip text for this block. - * @return The tooltip text for this block. + * + * @returns The tooltip text for this block. */ getTooltip(): string { return Tooltip.getTooltipOfObject(this); @@ -909,7 +947,8 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Get the colour of a block. - * @return #RRGGBB string. + * + * @returns #RRGGBB string. */ getColour(): string { return this.colour_; @@ -917,7 +956,8 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Get the name of the block style. - * @return Name of the block style. + * + * @returns Name of the block style. */ getStyleName(): string { return this.styleName_; @@ -925,7 +965,8 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Get the HSV hue value of a block. Null if hue not set. - * @return Hue value (0-360). + * + * @returns Hue value (0-360). */ getHue(): number|null { return this.hue_; @@ -933,6 +974,7 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Change the colour of a block. + * * @param colour HSV hue value (0 to 360), #RRGGBB string, or a message * reference string pointing to one of those two values. */ @@ -944,6 +986,7 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Set the style and colour values of a block. + * * @param blockStyleName Name of the block style. */ setStyle(blockStyleName: string) { @@ -955,6 +998,7 @@ export class Block implements IASTNodeLocation, IDeletable { * changes, replacing any prior onchange handler. This is usually only called * from the constructor, the block type initializer function, or an extension * initializer function. + * * @param onchangeFn The callback to call when the block's workspace changes. * @throws {Error} if onchangeFn is not falsey and not a function. */ @@ -972,8 +1016,9 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Returns the named field from a block. + * * @param name The name of the field. - * @return Named field, or null if field does not exist. + * @returns Named field, or null if field does not exist. */ getField(name: string): Field|null { if (typeof name !== 'string') { @@ -995,7 +1040,8 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Return all variables referenced by this block. - * @return List of variable ids. + * + * @returns List of variable ids. */ getVars(): string[] { const vars = []; @@ -1011,7 +1057,8 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Return all variables referenced by this block. - * @return List of variable models. + * + * @returns List of variable models. * @internal */ getVarModels(): VariableModel[] { @@ -1035,6 +1082,7 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Notification that a variable is renaming but keeping the same ID. If the * variable is in use on this block, rerender to show the new name. + * * @param variable The variable being renamed. * @internal */ @@ -1052,6 +1100,7 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Notification that a variable is renaming. * If the ID matches one of this block's variables, rename it. + * * @param oldId ID of variable to rename. * @param newId ID of new variable. May be the same as oldId, but with an * updated name. @@ -1068,8 +1117,9 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Returns the language-neutral value of the given field. + * * @param name The name of the field. - * @return Value of the field or null if field does not exist. + * @returns Value of the field or null if field does not exist. */ getFieldValue(name: string): AnyDuringMigration { const field = this.getField(name); @@ -1081,6 +1131,7 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Sets the value of the given field for this block. + * * @param newValue The value to set. * @param name The name of the field to set the value of. */ @@ -1094,6 +1145,7 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Set whether this block can chain onto the bottom of another block. + * * @param newBoolean True if there can be a previous statement. * @param opt_check Statement type or list of statement types. Null/undefined * if any type could be connected. @@ -1125,6 +1177,7 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Set whether another block can chain onto the bottom of this block. + * * @param newBoolean True if there can be a next statement. * @param opt_check Statement type or list of statement types. Null/undefined * if any type could be connected. @@ -1156,6 +1209,7 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Set whether this block returns a value. + * * @param newBoolean True if there is an output. * @param opt_check Returned type or list of returned types. Null or * undefined if any type could be returned (e.g. variable get). @@ -1186,6 +1240,7 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Set whether value inputs are arranged horizontally or vertically. + * * @param newBoolean True if inputs are horizontal. */ setInputsInline(newBoolean: boolean) { @@ -1198,7 +1253,8 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Get whether value inputs are arranged horizontally or vertically. - * @return True if inputs are horizontal. + * + * @returns True if inputs are horizontal. */ getInputsInline(): boolean { if (this.inputsInline !== undefined) { @@ -1225,6 +1281,7 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Set the block's output shape. + * * @param outputShape Value representing an output shape. */ setOutputShape(outputShape: number|null) { @@ -1233,7 +1290,8 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Get the block's output shape. - * @return Value representing output shape if one exists. + * + * @returns Value representing output shape if one exists. */ getOutputShape(): number|null { return this.outputShape_; @@ -1241,7 +1299,8 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Get whether this block is enabled or not. - * @return True if enabled. + * + * @returns True if enabled. */ isEnabled(): boolean { return !this.disabled; @@ -1249,6 +1308,7 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Set whether the block is enabled or not. + * * @param enabled True if enabled. */ setEnabled(enabled: boolean) { @@ -1263,7 +1323,8 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Get whether the block is disabled or not due to parents. * The block's own disabled property is not considered. - * @return True if disabled. + * + * @returns True if disabled. */ getInheritedDisabled(): boolean { let ancestor = this.getSurroundParent(); @@ -1279,7 +1340,8 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Get whether the block is collapsed or not. - * @return True if collapsed. + * + * @returns True if collapsed. */ isCollapsed(): boolean { return this.collapsed_; @@ -1287,6 +1349,7 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Set whether the block is collapsed or not. + * * @param collapsed True if collapsed. */ setCollapsed(collapsed: boolean) { @@ -1299,10 +1362,11 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Create a human-readable text representation of this block and any children. + * * @param opt_maxLength Truncate the string to this length. * @param opt_emptyToken The placeholder string used to denote an empty field. * If not specified, '?' is used. - * @return Text of block. + * @returns Text of block. */ toString(opt_maxLength?: number, opt_emptyToken?: string): string { let text = []; @@ -1317,8 +1381,9 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Whether or not to add parentheses around an input. + * * @param connection The connection. - * @return True if we should add parentheses around the input. + * @returns True if we should add parentheses around the input. */ function shouldAddParentheses(connection: Connection): boolean { let checks = connection.getCheck(); @@ -1417,9 +1482,10 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Shortcut for appending a value input row. + * * @param name Language-neutral identifier which may used to find this input * again. Should be unique to this block. - * @return The input object created. + * @returns The input object created. */ appendValueInput(name: string): Input { return this.appendInput_(inputTypes.VALUE, name); @@ -1427,9 +1493,10 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Shortcut for appending a statement input row. + * * @param name Language-neutral identifier which may used to find this input * again. Should be unique to this block. - * @return The input object created. + * @returns The input object created. */ appendStatementInput(name: string): Input { return this.appendInput_(inputTypes.STATEMENT, name); @@ -1437,9 +1504,10 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Shortcut for appending a dummy input row. + * * @param opt_name Language-neutral identifier which may used to find this * input again. Should be unique to this block. - * @return The input object created. + * @returns The input object created. */ appendDummyInput(opt_name?: string): Input { return this.appendInput_(inputTypes.DUMMY, opt_name || ''); @@ -1448,6 +1516,7 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Initialize this block using a cross-platform, internationalization-friendly * JSON description. + * * @param json Structured data describing the block. */ jsonInit(json: AnyDuringMigration) { @@ -1542,6 +1611,7 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Initialize the colour of this block from the JSON description. + * * @param json Structured data describing the block. * @param warningPrefix Warning prefix string identifying block. */ @@ -1562,6 +1632,7 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Initialize the style of this block from the JSON description. + * * @param json Structured data describing the block. * @param warningPrefix Warning prefix string identifying block. */ @@ -1580,6 +1651,7 @@ export class Block implements IASTNodeLocation, IDeletable { * the block, including prototype values. This provides some insurance against * mixin / extension incompatibilities with future block features. This check * can be disabled by passing true as the second argument. + * * @param mixinObj The key/values pairs to add to this block object. * @param opt_disableCheck Option flag to disable overwrite checks. */ @@ -1606,6 +1678,7 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Interpolate a message description onto the block. + * * @param message Text contains interpolation tokens (%1, %2, ...) that match * with fields or inputs defined in the args array. * @param args Array of arguments to be interpolated. @@ -1647,6 +1720,7 @@ export class Block implements IASTNodeLocation, IDeletable { * Validates that the tokens are within the correct bounds, with no * duplicates, and that all of the arguments are referred to. Throws errors if * any of these things are not true. + * * @param tokens An array of tokens to validate * @param argsCount The number of args that need to be referred to. */ @@ -1682,11 +1756,12 @@ export class Block implements IASTNodeLocation, IDeletable { * Inserts args in place of numerical tokens. String args are converted to * JSON that defines a label field. If necessary an extra dummy input is added * to the end of the elements. + * * @param tokens The tokens to interpolate * @param args The arguments to insert. * @param lastDummyAlign The alignment the added dummy input should have, if * we are required to add one. - * @return The JSON definitions of field and inputs to add to the block. + * @returns The JSON definitions of field and inputs to add to the block. */ private interpolateArguments_( tokens: Array, args: Array, @@ -1727,8 +1802,12 @@ export class Block implements IASTNodeLocation, IDeletable { * Creates a field from the JSON definition of a field. If a field with the * given type cannot be found, this attempts to create a different field using * the 'alt' property of the JSON definition (if it exists). + * * @param element The element to try to turn into a field. - * @return The field defined by the JSON, or null if one couldn't be created. + * @param element.alt + * @param element.type + * @param element.text + * @returns The field defined by the JSON, or null if one couldn't be created. */ private fieldFromJson_(element: {alt?: string, type?: string, text?: string}): Field|null { @@ -1746,10 +1825,11 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Creates an input from the JSON definition of an input. Sets the input's * check and alignment if they are provided. + * * @param element The JSON to turn into an input. * @param warningPrefix The prefix to add to warnings to help the developer * debug. - * @return The input that has been created, or null if one could not be + * @returns The input that has been created, or null if one could not be * created for some reason (should never happen). */ private inputFromJson_(element: AnyDuringMigration, warningPrefix: string): @@ -1796,8 +1876,9 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Returns true if the given string matches one of the input keywords. + * * @param str The string to check. - * @return True if the given string matches one of the input keywords, false + * @returns True if the given string matches one of the input keywords, false * otherwise. */ private isInputKeyword_(str: string): boolean { @@ -1808,8 +1889,9 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Turns a string into the JSON definition of a label field. If the string * becomes an empty string when trimmed, this returns null. + * * @param str String to turn into the JSON definition of a label field. - * @return The JSON definition or null. + * @returns The JSON definition or null. */ private stringToFieldJson_(str: string): {text: string, type: string}|null { str = str.trim(); @@ -1824,10 +1906,11 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Add a value input, statement input or local variable to this block. + * * @param type One of Blockly.inputTypes. * @param name Language-neutral identifier which may used to find this input * again. Should be unique to this block. - * @return The input object created. + * @returns The input object created. */ protected appendInput_(type: number, name: string): Input { let connection = null; @@ -1848,6 +1931,7 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Move a named input to a different location on this block. + * * @param name The name of the input to move. * @param refName Name of input that should be after the moved input, or null * to be the input at the end. @@ -1883,6 +1967,7 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Move a numbered input to a different location on this block. + * * @param inputIndex Index of the input to move. * @param refIndex Index of input that should be after the moved input. */ @@ -1909,9 +1994,10 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Remove an input from this block. + * * @param name The name of the input. * @param opt_quiet True to prevent an error if input is not present. - * @return True if operation succeeds, false if input is not present and + * @returns True if operation succeeds, false if input is not present and * opt_quiet is true. * @throws {Error} if the input is not present and opt_quiet is not true. */ @@ -1934,8 +2020,9 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Fetches the named input object. + * * @param name The name of the input. - * @return The input object, or null if input does not exist. + * @returns The input object, or null if input does not exist. */ getInput(name: string): Input|null { for (let i = 0, input; input = this.inputList[i]; i++) { @@ -1949,8 +2036,9 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Fetches the block attached to the named input. + * * @param name The name of the input. - * @return The attached value block, or null if the input is either + * @returns The attached value block, or null if the input is either * disconnected or if the input does not exist. */ getInputTargetBlock(name: string): Block|null { @@ -1960,7 +2048,8 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Returns the comment on this block (or null if there is no comment). - * @return Block's comment. + * + * @returns Block's comment. */ getCommentText(): string|null { return this.commentModel.text; @@ -1968,6 +2057,7 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Set this block's comment text. + * * @param text The text, or null to delete. */ setCommentText(text: string|null) { @@ -1984,6 +2074,7 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Set this block's warning text. + * * @param _text The text, or null to delete. * @param _opt_id An optional ID for the warning text to be able to maintain * multiple warnings. @@ -1993,6 +2084,7 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Give this block a mutator dialog. + * * @param _mutator A mutator dialog instance or null to remove. */ setMutator(_mutator: Mutator) {} @@ -2001,7 +2093,8 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Return the coordinates of the top-left corner of this block relative to the * drawing surface's origin (0,0), in workspace units. - * @return Object with .x and .y properties. + * + * @returns Object with .x and .y properties. */ getRelativeToSurfaceXY(): Coordinate { return this.xy_; @@ -2009,6 +2102,7 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Move a block by a relative offset. + * * @param dx Horizontal offset, in workspace units. * @param dy Vertical offset, in workspace units. */ @@ -2025,8 +2119,9 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Create a connection of the specified type. + * * @param type The type of the connection to create. - * @return A new connection of the specified type. + * @returns A new connection of the specified type. */ protected makeConnection_(type: number): Connection { return new Connection(this, type); @@ -2035,9 +2130,10 @@ export class Block implements IASTNodeLocation, IDeletable { /** * Recursively checks whether all statement and value inputs are filled with * blocks. Also checks all following statement blocks in this stack. + * * @param opt_shadowBlocksAreFilled An optional argument controlling whether * shadow blocks are counted as filled. Defaults to true. - * @return True if all inputs are filled, false otherwise. + * @returns True if all inputs are filled, false otherwise. */ allInputsFilled(opt_shadowBlocksAreFilled?: boolean): boolean { // Account for the shadow block filledness toggle. @@ -2075,7 +2171,8 @@ export class Block implements IASTNodeLocation, IDeletable { * Intended to on be used in console logs and errors. If you need a string * that uses the user's native language (including block text, field values, * and child blocks), use [toString()]{@link Block#toString}. - * @return The description. + * + * @returns The description. */ toDevString(): string { let msg = this.type ? '"' + this.type + '" block' : 'Block'; diff --git a/core/block_drag_surface.ts b/core/block_drag_surface.ts index b6373feba..7238e6313 100644 --- a/core/block_drag_surface.ts +++ b/core/block_drag_surface.ts @@ -11,6 +11,7 @@ * blocks are put back in into the SVG they came from. This helps * performance by avoiding repainting the entire SVG on every mouse move * while dragging blocks. + * * @class */ import * as goog from '../closure/goog/goog.js'; @@ -26,6 +27,7 @@ import * as svgMath from './utils/svg_math.js'; /** * Class for a drag surface for the currently dragged block. This is a separate * SVG that contains only the currently moving block, or nothing. + * * @alias Blockly.BlockDragSurfaceSvg */ export class BlockDragSurfaceSvg { @@ -83,6 +85,7 @@ export class BlockDragSurfaceSvg { /** * Set the SVG blocks on the drag surface's group and show the surface. * Only one block group should be on the drag surface at a time. + * * @param blocks Block or group of blocks to place on the drag surface. */ setBlocksAndShow(blocks: SVGElement) { @@ -98,6 +101,7 @@ export class BlockDragSurfaceSvg { /** * Translate and scale the entire drag surface group to the given position, to * keep in sync with the workspace. + * * @param x X translation in pixel coordinates. * @param y Y translation in pixel coordinates. * @param scale Scale of the group. @@ -116,6 +120,7 @@ export class BlockDragSurfaceSvg { /** * Translate the drag surface's SVG based on its internal state. + * * @private */ translateSurfaceInternal_() { @@ -130,6 +135,7 @@ export class BlockDragSurfaceSvg { /** * Translates the entire surface by a relative offset. + * * @param deltaX Horizontal offset in pixel units. * @param deltaY Vertical offset in pixel units. */ @@ -145,6 +151,7 @@ export class BlockDragSurfaceSvg { * We translate the drag surface instead of the blocks inside the surface * so that the browser avoids repainting the SVG. * Because of this, the drag coordinates must be adjusted by scale. + * * @param x X translation for the entire surface. * @param y Y translation for the entire surface. */ @@ -156,7 +163,8 @@ export class BlockDragSurfaceSvg { /** * Reports the surface translation in scaled workspace coordinates. * Use this when finishing a drag to return blocks to the correct position. - * @return Current translation of the surface. + * + * @returns Current translation of the surface. */ getSurfaceTranslation(): Coordinate { const xy = svgMath.getRelativeXY(this.svg_ as SVGElement); @@ -166,7 +174,8 @@ export class BlockDragSurfaceSvg { /** * Provide a reference to the drag group (primarily for * BlockSvg.getRelativeToSurfaceXY). - * @return Drag surface group element. + * + * @returns Drag surface group element. */ getGroup(): SVGElement|null { return this.dragGroup_; @@ -174,6 +183,7 @@ export class BlockDragSurfaceSvg { /** * Returns the SVG drag surface. + * * @returns The SVG drag surface. */ getSvgRoot(): SVGElement|null { @@ -183,7 +193,8 @@ export class BlockDragSurfaceSvg { /** * Get the current blocks on the drag surface, if any (primarily * for BlockSvg.getRelativeToSurfaceXY). - * @return Drag surface block DOM element, or null if no blocks exist. + * + * @returns Drag surface block DOM element, or null if no blocks exist. */ getCurrentBlock(): Element|null { return this.dragGroup_.firstChild as Element; @@ -193,7 +204,8 @@ export class BlockDragSurfaceSvg { * Gets the translation of the child block surface * This surface is in charge of keeping track of how much the workspace has * moved. - * @return The amount the workspace has been moved. + * + * @returns The amount the workspace has been moved. */ getWsTranslation(): Coordinate { // Returning a copy so the coordinate can not be changed outside this class. @@ -205,6 +217,7 @@ export class BlockDragSurfaceSvg { * element. * If the block is being deleted it doesn't need to go back to the original * surface, since it would be removed immediately during dispose. + * * @param opt_newSurface Surface the dragging blocks should be moved to, or * null if the blocks should be removed from this surface without being * moved to a different surface. diff --git a/core/block_dragger.ts b/core/block_dragger.ts index 16867265e..5e336fb96 100644 --- a/core/block_dragger.ts +++ b/core/block_dragger.ts @@ -6,6 +6,7 @@ /** * Methods for dragging a block visually. + * * @class */ import * as goog from '../closure/goog/goog.js'; @@ -33,6 +34,7 @@ import type {WorkspaceSvg} from './workspace_svg.js'; /** * Class for a block dragger. It moves blocks around the workspace when they * are being dragged by a mouse or touch. + * * @alias Blockly.BlockDragger */ export class BlockDragger implements IBlockDragger { @@ -80,6 +82,7 @@ export class BlockDragger implements IBlockDragger { /** * Sever all links from this object. + * * @internal */ dispose() { @@ -92,6 +95,7 @@ export class BlockDragger implements IBlockDragger { /** * Start dragging a block. This includes moving it to the drag surface. + * * @param currentDragDeltaXY How far the pointer has moved from the position * at mouse down, in pixel units. * @param healStack Whether or not to heal the stack after disconnecting. @@ -128,8 +132,9 @@ export class BlockDragger implements IBlockDragger { /** * Whether or not we should disconnect the block when a drag is started. + * * @param healStack Whether or not to heal the stack after disconnecting. - * @return True to disconnect the block, false otherwise. + * @returns True to disconnect the block, false otherwise. */ protected shouldDisconnect_(healStack: boolean): boolean { return !!( @@ -140,6 +145,7 @@ export class BlockDragger implements IBlockDragger { /** * Disconnects the block and moves it to a new location. + * * @param healStack Whether or not to heal the stack after disconnecting. * @param currentDragDeltaXY How far the pointer has moved from the position * at mouse down, in pixel units. @@ -165,6 +171,7 @@ export class BlockDragger implements IBlockDragger { /** * Execute a step of block dragging, based on the given event. Update the * display accordingly. + * * @param e The most recent move event. * @param currentDragDeltaXY How far the pointer has moved from the position * at the start of the drag, in pixel units. @@ -197,6 +204,7 @@ export class BlockDragger implements IBlockDragger { /** * Finish a block drag and put the block back on the workspace. + * * @param e The mouseup/touchend event. * @param currentDragDeltaXY How far the pointer has moved from the position * at the start of the drag, in pixel units. @@ -250,9 +258,10 @@ export class BlockDragger implements IBlockDragger { /** * Calculates the drag delta and new location values after a block is dragged. + * * @param currentDragDeltaXY How far the pointer has moved from the start of * the drag, in pixel units. - * @return New location after drag. delta is in workspace units. newLocation + * @returns New location after drag. delta is in workspace units. newLocation * is the new coordinate where the block should end up. */ protected getNewLocationAfterDrag_(currentDragDeltaXY: Coordinate): @@ -269,7 +278,8 @@ export class BlockDragger implements IBlockDragger { * May delete the dragging block, if allowed. If `this.wouldDeleteBlock_` is * not true, the block will not be deleted. This should be called at the end * of a block drag. - * @return True if the block was deleted. + * + * @returns True if the block was deleted. */ protected maybeDeleteBlock_(): boolean { if (this.wouldDeleteBlock_) { @@ -284,6 +294,7 @@ export class BlockDragger implements IBlockDragger { /** * Updates the necessary information to place a block at a certain location. + * * @param delta The change in location from where the block started the drag * to where it ended the drag. */ @@ -310,6 +321,7 @@ export class BlockDragger implements IBlockDragger { * Adds or removes the style of the cursor for the toolbox. * This is what changes the cursor to display an x when a deletable block is * held over the toolbox. + * * @param isEnd True if we are at the end of a drag, false otherwise. */ protected updateToolboxStyle_(isEnd: boolean) { @@ -360,8 +372,9 @@ export class BlockDragger implements IBlockDragger { * correction for mutator workspaces. * This function does not consider differing origins. It simply scales the * input's x and y values. + * * @param pixelCoord A coordinate with x and y values in CSS pixel units. - * @return The input coordinate divided by the workspace scale. + * @returns The input coordinate divided by the workspace scale. */ protected pixelsToWorkspaceUnits_(pixelCoord: Coordinate): Coordinate { const result = new Coordinate( @@ -379,6 +392,7 @@ export class BlockDragger implements IBlockDragger { /** * Move all of the icons connected to this drag. + * * @param dxy How far to move the icons from their original positions, in * workspace units. */ @@ -393,7 +407,8 @@ export class BlockDragger implements IBlockDragger { /** * Get a list of the insertion markers that currently exist. Drags have 0, 1, * or 2 insertion markers. - * @return A possibly empty list of insertion marker blocks. + * + * @returns A possibly empty list of insertion marker blocks. */ getInsertionMarkers(): BlockSvg[] { // No insertion markers with the old style of dragged connection managers. @@ -415,8 +430,9 @@ export interface IconPositionData { * Make a list of all of the icons (comment, warning, and mutator) that are * on this block and its descendants. Moving an icon moves the bubble that * extends from it if that bubble is open. + * * @param block The root block that is being dragged. - * @return The list of all icons and their locations. + * @returns The list of all icons and their locations. */ function initIconData(block: BlockSvg): IconPositionData[] { // Build a list of icons that need to be moved and where they started. diff --git a/core/block_svg.ts b/core/block_svg.ts index dbd707d9b..0597cc337 100644 --- a/core/block_svg.ts +++ b/core/block_svg.ts @@ -6,6 +6,7 @@ /** * Methods for graphically rendering a block as SVG. + * * @class */ import * as goog from '../closure/goog/goog.js'; @@ -65,6 +66,7 @@ import type {WorkspaceSvg} from './workspace_svg.js'; /** * Class for a block's SVG representation. * Not normally called directly, workspace.newBlock() is preferred. + * * @alias Blockly.BlockSvg */ export class BlockSvg extends Block implements IASTNodeLocationSvg, @@ -91,6 +93,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, /** * An property used internally to reference the block's rendering debugger. + * * @internal */ renderingDebugger: BlockRenderingDebug|null = null; @@ -241,7 +244,8 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, /** * Get the secondary colour of a block. - * @return #RRGGBB string. + * + * @returns #RRGGBB string. */ getColourSecondary(): string|null { return this.style.colourSecondary; @@ -249,7 +253,8 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, /** * Get the tertiary colour of a block. - * @return #RRGGBB string. + * + * @returns #RRGGBB string. */ getColourTertiary(): string|null { return this.style.colourTertiary; @@ -304,7 +309,8 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, /** * Returns a list of mutator, comment, and warning icons. - * @return List of icons. + * + * @returns List of icons. */ getIcons(): Icon[] { const icons = []; @@ -322,6 +328,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, /** * Sets the parent of this block to be a new block or null. + * * @param newParent New parent block. * @internal */ @@ -367,7 +374,8 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, * If the block is on the workspace, (0, 0) is the origin of the workspace * coordinate system. * This does not change with workspace scale. - * @return Object with .x and .y properties in workspace coordinates. + * + * @returns Object with .x and .y properties in workspace coordinates. */ override getRelativeToSurfaceXY(): Coordinate { let x = 0; @@ -403,6 +411,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, /** * Move a block by a relative offset. + * * @param dx Horizontal offset in workspace units. * @param dy Vertical offset in workspace units. */ @@ -428,6 +437,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, /** * Transforms a block by setting the translation on the transform attribute * of the block's SVG. + * * @param x The x coordinate of the translation in workspace units. * @param y The y coordinate of the translation in workspace units. */ @@ -440,6 +450,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, * Move this block to its workspace's drag surface, accounting for * positioning. Generally should be called at the same time as * setDragging_(true). Does nothing if useDragSurface_ is false. + * * @internal */ moveToDragSurface() { @@ -462,6 +473,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, /** * Move a block to a position. + * * @param xy The position to move to in workspace units. */ moveTo(xy: Coordinate) { @@ -473,6 +485,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, * Move this block back to the workspace block canvas. * Generally should be called at the same time as setDragging_(false). * Does nothing if useDragSurface_ is false. + * * @param newXY The position the block should take on on the workspace canvas, * in workspace coordinates. * @internal @@ -491,6 +504,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, * Move this block during a drag, taking into account whether we are using a * drag surface to translate blocks. * This block must be a top-level block. + * * @param newLoc The location to translate to, in workspace coordinates. * @internal */ @@ -552,7 +566,8 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, * Returns the coordinates of a bounding box describing the dimensions of this * block and any blocks stacked below it. * Coordinate system: workspace coordinates. - * @return Object with coordinates of the bounding box. + * + * @returns Object with coordinates of the bounding box. */ getBoundingRectangle(): Rect { const blockXY = this.getRelativeToSurfaceXY(); @@ -582,6 +597,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, /** * Set whether the block is collapsed or not. + * * @param collapsed True if collapsed. */ override setCollapsed(collapsed: boolean) { @@ -640,6 +656,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, /** * Open the next (or previous) FieldTextInput. + * * @param start Current field. * @param forward If true go forward, otherwise backward. */ @@ -668,6 +685,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, /** * Handle a mouse-down on an SVG block. + * * @param e Mouse down event or touch start event. */ private onMouseDown_(e: Event) { @@ -679,6 +697,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, /** * Load the block's help page in a new window. + * * @internal */ showHelp() { @@ -691,7 +710,8 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, /** * Generate the context menu for this block. - * @return Context menu options or null if no menu. + * + * @returns Context menu options or null if no menu. */ protected generateContextMenu(): Array|null { @@ -714,6 +734,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, /** * Show the context menu for this block. + * * @param e Mouse event. * @internal */ @@ -731,6 +752,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, /** * Move the connections for this block and all blocks attached under it. * Also update any attached bubbles. + * * @param dx Horizontal offset from current location, in workspace units. * @param dy Vertical offset from current location, in workspace units. * @internal @@ -759,6 +781,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, /** * Recursively adds or removes the dragging class to this node and its * children. + * * @param adding True if adding, false if removing. * @internal */ @@ -781,6 +804,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, /** * Set whether this block is movable or not. + * * @param movable True if movable. */ override setMovable(movable: boolean) { @@ -790,6 +814,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, /** * Set whether this block is editable or not. + * * @param editable True if editable. */ override setEditable(editable: boolean) { @@ -802,6 +827,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, /** * Sets whether this block is a shadow block or not. + * * @param shadow True if a shadow. * @internal */ @@ -813,6 +839,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, /** * Set whether this block is an insertion marker block or not. * Once set this cannot be unset. + * * @param insertionMarker True if an insertion marker. * @internal */ @@ -830,7 +857,8 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, /** * Return the root node of the SVG or null if none exists. - * @return The root SVG node (probably a group). + * + * @returns The root SVG node (probably a group). */ getSvgRoot(): SVGGElement { return this.svgGroup_; @@ -838,6 +866,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, /** * Dispose of this block. + * * @param healStack If true, then try to heal any gap by connecting the next * statement with the previous statement. Otherwise, dispose of all * children of this block. @@ -927,7 +956,8 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, /** * Encode a block for copying. - * @return Copy metadata, or null if the block is an insertion marker. + * + * @returns Copy metadata, or null if the block is an insertion marker. * @internal */ toCopyData(): CopyData|null { @@ -949,6 +979,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, /** * Updates the colour of the block to match the block's state. + * * @internal */ applyColour() { @@ -969,6 +1000,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, /** * Updates the color of the block (and children) to match the current disabled * state. + * * @internal */ updateDisabled() { @@ -987,7 +1019,8 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, /** * Get the comment icon attached to this block, or null if the block has no * comment. - * @return The comment icon attached to this block, or null. + * + * @returns The comment icon attached to this block, or null. */ getCommentIcon(): Comment|null { return this.commentIcon_; @@ -995,6 +1028,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, /** * Set this block's comment text. + * * @param text The text, or null to delete. */ override setCommentText(text: string|null) { @@ -1029,6 +1063,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, /** * Set this block's warning text. + * * @param text The text, or null to delete. * @param opt_id An optional ID for the warning text to be able to maintain * multiple warnings. @@ -1107,6 +1142,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, /** * Give this block a mutator dialog. + * * @param mutator A mutator dialog instance or null to remove. */ override setMutator(mutator: Mutator|null) { @@ -1127,6 +1163,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, /** * Set whether the block is enabled or not. + * * @param enabled True if enabled. */ override setEnabled(enabled: boolean) { @@ -1141,6 +1178,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, /** * Set whether the block is highlighted or not. Block highlighting is * often used to visually mark blocks currently being executed. + * * @param highlighted True if highlighted. */ setHighlighted(highlighted: boolean) { @@ -1153,6 +1191,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, /** * Adds the visual "select" effect to the block, but does not actually select * it or fire an event. + * * @see BlockSvg#select */ addSelect() { @@ -1162,6 +1201,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, /** * Removes the visual "select" effect from the block, but does not actually * unselect it or fire an event. + * * @see BlockSvg#unselect */ removeSelect() { @@ -1170,6 +1210,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, /** * Update the cursor over this block by adding or removing a class. + * * @param enable True if the delete cursor should be shown, false otherwise. * @internal */ @@ -1183,7 +1224,8 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, /** * Get the colour of a block. - * @return #RRGGBB string. + * + * @returns #RRGGBB string. */ override getColour(): string { return this.style.colourPrimary; @@ -1191,6 +1233,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, /** * Change the colour of a block. + * * @param colour HSV hue value, or #RRGGBB string. */ override setColour(colour: number|string) { @@ -1208,6 +1251,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, /** * Set the style and colour values of a block. + * * @param blockStyleName Name of the block style. * @throws {Error} if the block style does not exist. */ @@ -1235,6 +1279,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, * tags do not respect z-index so SVG renders them in the * order that they are in the DOM. By placing this block first within the * block group's , it will render on top of any other blocks. + * * @internal */ bringToFront() { @@ -1255,6 +1300,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, /** * Set whether this block can chain onto the bottom of another block. + * * @param newBoolean True if there can be a previous statement. * @param opt_check Statement type or list of statement types. Null/undefined * if any type could be connected. @@ -1271,6 +1317,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, /** * Set whether another block can chain onto the bottom of this block. + * * @param newBoolean True if there can be a next statement. * @param opt_check Statement type or list of statement types. Null/undefined * if any type could be connected. @@ -1287,6 +1334,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, /** * Set whether this block returns a value. + * * @param newBoolean True if there is an output. * @param opt_check Returned type or list of returned types. Null or * undefined if any type could be returned (e.g. variable get). @@ -1302,6 +1350,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, /** * Set whether value inputs are arranged horizontally or vertically. + * * @param newBoolean True if inputs are horizontal. */ override setInputsInline(newBoolean: boolean) { @@ -1315,9 +1364,10 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, /** * Remove an input from this block. + * * @param name The name of the input. * @param opt_quiet True to prevent error if input is not present. - * @return True if operation succeeds, false if input is not present and + * @returns True if operation succeeds, false if input is not present and * opt_quiet is true * @throws {Error} if the input is not present and opt_quiet is not true. */ @@ -1335,6 +1385,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, /** * Move a numbered input to a different location on this block. + * * @param inputIndex Index of the input to move. * @param refIndex Index of input that should be after the moved input. */ @@ -1350,10 +1401,11 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, /** * Add a value input, statement input or local variable to this block. + * * @param type One of Blockly.inputTypes. * @param name Language-neutral identifier which may used to find this input * again. Should be unique to this block. - * @return The input object created. + * @returns The input object created. */ protected override appendInput_(type: number, name: string): Input { const input = super.appendInput_(type, name); @@ -1372,6 +1424,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, * Used by the deserializer to be more efficient. Setting a connection's * tracked_ value to false keeps it from adding itself to the db when it * gets its first moveTo call, saving expensive ops for later. + * * @param track If true, start tracking. If false, stop tracking. * @internal */ @@ -1413,10 +1466,11 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, /** * Returns connections originating from this block. + * * @param all If true, return all connections even hidden ones. * Otherwise, for a non-rendered block return an empty list, and for a * collapsed block don't return inputs connections. - * @return Array of connections. + * @returns Array of connections. * @internal */ override getConnections_(all: boolean): RenderedConnection[] { @@ -1445,10 +1499,11 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, /** * Walks down a stack of blocks and finds the last next connection on the * stack. + * * @param ignoreShadows If true,the last connection on a non-shadow block will * be returned. If false, this will follow shadows to find the last * connection. - * @return The last next connection on the stack, or null. + * @returns The last next connection on the stack, or null. * @internal */ override lastConnectionInStack(ignoreShadows: boolean): RenderedConnection @@ -1460,9 +1515,10 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, * Find the connection on this block that corresponds to the given connection * on the other block. * Used to match connections between a block and its insertion marker. + * * @param otherBlock The other block to match against. * @param conn The other connection to match. - * @return The matching connection on this block, or null. + * @returns The matching connection on this block, or null. * @internal */ override getMatchingConnection(otherBlock: Block, conn: Connection): @@ -1472,8 +1528,9 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, /** * Create a connection of the specified type. + * * @param type The type of the connection to create. - * @return A new connection of the specified type. + * @returns A new connection of the specified type. */ protected override makeConnection_(type: number): RenderedConnection { return new RenderedConnection(this, type); @@ -1481,7 +1538,8 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, /** * Return the next statement block directly connected to this block. - * @return The next statement block or null. + * + * @returns The next statement block or null. */ override getNextBlock(): BlockSvg|null { return super.getNextBlock() as BlockSvg; @@ -1489,7 +1547,8 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, /** * Returns the block connected to the previous connection. - * @return The previous statement block or null. + * + * @returns The previous statement block or null. */ override getPreviousBlock(): BlockSvg|null { return super.getPreviousBlock() as BlockSvg; @@ -1543,6 +1602,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, /** * Schedule snapping to grid and bumping neighbours to occur after a brief * delay. + * * @internal */ scheduleSnapAndBump() { @@ -1567,6 +1627,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, * Position a block so that it doesn't move the target block when connected. * The block to position is usually either the first block in a dragged stack * or an insertion marker. + * * @param sourceConnection The connection on the moving block's stack. * @param targetConnection The connection that should stay stationary as this * block is positioned. @@ -1587,7 +1648,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, } /** - * @return The first statement connection or null. + * @returns The first statement connection or null. * @internal */ override getFirstStatementConnection(): RenderedConnection|null { @@ -1599,8 +1660,9 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, * Includes value and statement inputs, as well as any following statement. * Excludes any connection on an output tab or any preceding statement. * Blocks are optionally sorted by position; top to bottom. + * * @param ordered Sort the list if true. - * @return Array of blocks. + * @returns Array of blocks. */ override getChildren(ordered: boolean): BlockSvg[] { return super.getChildren(ordered) as BlockSvg[]; @@ -1608,6 +1670,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, /** * Lays out and reflows a block based on its contents and settings. + * * @param opt_bubble If false, just render this block. * If true, also render block's parent, grandparent, etc. Defaults to true. */ @@ -1690,6 +1753,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, /** * Add the cursor SVG to this block's SVG group. + * * @param cursorSvg The SVG root of the cursor to be added to the block SVG * group. * @internal @@ -1700,6 +1764,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, /** * Add the marker SVG to this block's SVG group. + * * @param markerSvg The SVG root of the marker to be added to the block SVG * group. * @internal @@ -1711,7 +1776,8 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, /** * Returns a bounding box describing the dimensions of this block * and any blocks stacked below it. - * @return Object with height and width properties in workspace units. + * + * @returns Object with height and width properties in workspace units. * @internal */ getHeightWidth(): {height: number, width: number} { @@ -1733,6 +1799,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, * Visual effect to show that if the dragging block is dropped, this block * will be replaced. If a shadow block, it will disappear. Otherwise it will * bump. + * * @param add True if highlighting should be added. * @internal */ @@ -1743,6 +1810,7 @@ export class BlockSvg extends Block implements IASTNodeLocationSvg, /** * Visual effect to show that if the dragging block is dropped it will connect * to this input. + * * @param conn The connection on the input to highlight. * @param add True if highlighting should be added. * @internal diff --git a/core/blockly_options.ts b/core/blockly_options.ts index 0613a9fe6..0cf4c851d 100644 --- a/core/blockly_options.ts +++ b/core/blockly_options.ts @@ -6,6 +6,7 @@ /** * Object that defines user-specified options for the workspace. + * * @namespace Blockly.BlocklyOptions */ import * as goog from '../closure/goog/goog.js'; @@ -18,6 +19,7 @@ import type {ToolboxDefinition} from './utils/toolbox.js'; /** * Blockly options. + * * @alias Blockly.BlocklyOptions */ export interface BlocklyOptions { diff --git a/core/blocks.ts b/core/blocks.ts index 37ad4d01a..aecf6eb69 100644 --- a/core/blocks.ts +++ b/core/blocks.ts @@ -6,6 +6,7 @@ /** * A mapping of block type names to block prototype objects. + * * @namespace Blockly.blocks */ import * as goog from '../closure/goog/goog.js'; @@ -20,6 +21,7 @@ export type BlockDefinition = AnyDuringMigration; /** * A mapping of block type names to block prototype objects. + * * @alias Blockly.blocks.Blocks */ export const Blocks: {[key: string]: BlockDefinition} = Object.create(null); diff --git a/core/bubble.ts b/core/bubble.ts index 483f487f6..c8b4fdf74 100644 --- a/core/bubble.ts +++ b/core/bubble.ts @@ -6,6 +6,7 @@ /** * Object representing a UI bubble. + * * @class */ import * as goog from '../closure/goog/goog.js'; @@ -35,6 +36,7 @@ import type {WorkspaceSvg} from './workspace_svg.js'; /** * Class for UI bubble. + * * @alias Blockly.Bubble */ export class Bubble implements IBubble { @@ -125,6 +127,7 @@ export class Bubble implements IBubble { /** * Describes whether this bubble has been disposed of (nodes and event * listeners removed from the page) or not. + * * @internal */ disposed = false; @@ -174,9 +177,10 @@ export class Bubble implements IBubble { /** * Create the bubble's DOM. + * * @param content SVG content for the bubble. * @param hasResize Add diagonal resize gripper if true. - * @return The bubble's SVG group. + * @returns The bubble's SVG group. */ private createDom_(content: Element, hasResize: boolean): SVGElement { /* Create the bubble. Here's the markup that will be generated: @@ -263,7 +267,8 @@ export class Bubble implements IBubble { /** * Return the root node of the bubble's SVG group. - * @return The root SVG node of the bubble's group. + * + * @returns The root SVG node of the bubble's group. */ getSvgRoot(): SVGElement { return this.bubbleGroup_ as SVGElement; @@ -271,6 +276,7 @@ export class Bubble implements IBubble { /** * Expose the block's ID on the bubble's top-level SVG group. + * * @param id ID of block. */ setSvgId(id: string) { @@ -279,6 +285,7 @@ export class Bubble implements IBubble { /** * Handle a mouse-down on bubble's border. + * * @param e Mouse down event. */ private bubbleMouseDown_(e: Event) { @@ -290,6 +297,7 @@ export class Bubble implements IBubble { /** * Show the context menu for this bubble. + * * @param _e Mouse event. * @internal */ @@ -299,7 +307,8 @@ export class Bubble implements IBubble { /** * Get whether this bubble is deletable or not. - * @return True if deletable. + * + * @returns True if deletable. * @internal */ isDeletable(): boolean { @@ -308,6 +317,7 @@ export class Bubble implements IBubble { /** * Update the style of this bubble when it is dragged over a delete area. + * * @param _enable True if the bubble is about to be deleted, false otherwise. */ setDeleteStyle(_enable: boolean) {} @@ -315,6 +325,7 @@ export class Bubble implements IBubble { /** * Handle a mouse-down on bubble's resize corner. + * * @param e Mouse down event. */ private resizeMouseDown_(e: MouseEvent) { @@ -342,6 +353,7 @@ export class Bubble implements IBubble { /** * Resize this bubble to follow the mouse. + * * @param e Mouse move event. */ private resizeMouseMove_(e: MouseEvent) { @@ -356,6 +368,7 @@ export class Bubble implements IBubble { /** * Register a function as a callback event for when the bubble is resized. + * * @param callback The function to call on resize. */ registerResizeEvent(callback: () => void) { @@ -364,6 +377,7 @@ export class Bubble implements IBubble { /** * Register a function as a callback event for when the bubble is moved. + * * @param callback The function to call on move. */ registerMoveEvent(callback: () => void) { @@ -372,7 +386,8 @@ export class Bubble implements IBubble { /** * Move this bubble to the top of the stack. - * @return Whether or not the bubble has been moved. + * + * @returns Whether or not the bubble has been moved. * @internal */ promote(): boolean { @@ -387,6 +402,7 @@ export class Bubble implements IBubble { /** * Notification that the anchor has moved. * Update the arrow and bubble accordingly. + * * @param xy Absolute location. */ setAnchorLocation(xy: Coordinate) { @@ -457,11 +473,14 @@ export class Bubble implements IBubble { /** * Calculate the what percentage of the bubble overlaps with the visible * workspace (what percentage of the bubble is visible). + * * @param relativeMin The position of the top-left corner of the bubble * relative to the anchor point. + * @param relativeMin.x * @param viewMetrics The view metrics of the workspace the bubble will appear * in. - * @return The percentage of the bubble that is visible. + * @param relativeMin.y + * @returns The percentage of the bubble that is visible. */ private getOverlap_( relativeMin: {x: number, y: number}, @@ -505,9 +524,10 @@ export class Bubble implements IBubble { * Calculate what the optimal horizontal position of the top-left corner of * the bubble is (relative to the anchor point) so that the most area of the * bubble is shown. + * * @param viewMetrics The view metrics of the workspace the bubble will appear * in. - * @return The optimal horizontal position of the top-left corner of the + * @returns The optimal horizontal position of the top-left corner of the * bubble. */ private getOptimalRelativeLeft_(viewMetrics: ContainerRegion): number { @@ -560,9 +580,10 @@ export class Bubble implements IBubble { * Calculate what the optimal vertical position of the top-left corner of * the bubble is (relative to the anchor point) so that the most area of the * bubble is shown. + * * @param viewMetrics The view metrics of the workspace the bubble will appear * in. - * @return The optimal vertical position of the top-left corner of the bubble. + * @returns The optimal vertical position of the top-left corner of the bubble. */ private getOptimalRelativeTop_(viewMetrics: ContainerRegion): number { let relativeTop = -this.height_ / 4; @@ -605,6 +626,7 @@ export class Bubble implements IBubble { /** * Move the bubble group to the specified location in workspace coordinates. + * * @param x The x position to move to. * @param y The y position to move to. * @internal @@ -616,6 +638,7 @@ export class Bubble implements IBubble { /** * Triggers a move callback if one exists at the end of a drag. + * * @param adding True if adding, false if removing. * @internal */ @@ -627,7 +650,8 @@ export class Bubble implements IBubble { /** * Get the dimensions of this bubble. - * @return The height and width of the bubble. + * + * @returns The height and width of the bubble. */ getBubbleSize(): Size { return new Size(this.width_, this.height_); @@ -635,6 +659,7 @@ export class Bubble implements IBubble { /** * Size this bubble. + * * @param width Width of the bubble. * @param height Height of the bubble. */ @@ -746,6 +771,7 @@ export class Bubble implements IBubble { /** * Change the colour of a bubble. + * * @param hexColour Hex code of colour. */ setColour(hexColour: string) { @@ -769,6 +795,7 @@ export class Bubble implements IBubble { /** * Move this bubble during a drag, taking into account whether or not there is * a drag surface. + * * @param dragSurface The surface that carries rendered items during a drag, * or null if no drag surface is in use. * @param newLoc The location to translate to, in workspace coordinates. @@ -792,7 +819,8 @@ export class Bubble implements IBubble { /** * Return the coordinates of the top-left corner of this bubble's body * relative to the drawing surface's origin (0,0), in workspace units. - * @return Object with .x and .y properties. + * + * @returns Object with .x and .y properties. */ getRelativeToSurfaceXY(): Coordinate { return new Coordinate( @@ -806,6 +834,7 @@ export class Bubble implements IBubble { * Set whether auto-layout of this bubble is enabled. The first time a bubble * is shown it positions itself to not cover any blocks. Once a user has * dragged it to reposition, it renders where the user put it. + * * @param enable True if auto-layout should be enabled, false otherwise. * @internal */ @@ -827,6 +856,7 @@ export class Bubble implements IBubble { /** * Handle a mouse-up event while dragging a bubble's border or resize handle. + * * @param _e Mouse up event. */ private static bubbleMouseUp_(_e: MouseEvent) { @@ -836,8 +866,9 @@ export class Bubble implements IBubble { /** * Create the text for a non editable bubble. + * * @param text The text to display. - * @return The top-level node of the text. + * @returns The top-level node of the text. * @internal */ static textToDom(text: string): SVGTextElement { @@ -857,10 +888,11 @@ export class Bubble implements IBubble { /** * Creates a bubble that can not be edited. + * * @param paragraphElement The text element for the non editable bubble. * @param block The block that the bubble is attached to. * @param iconXY The coordinate of the icon. - * @return The non editable bubble. + * @returns The non editable bubble. * @internal */ static createNonEditableBubble( diff --git a/core/clipboard.ts b/core/clipboard.ts index 6250b7359..0842d8c3d 100644 --- a/core/clipboard.ts +++ b/core/clipboard.ts @@ -6,6 +6,7 @@ /** * Blockly's internal clipboard for managing copy-paste. + * * @namespace Blockly.clipboard */ import * as goog from '../closure/goog/goog.js'; @@ -19,6 +20,7 @@ let copyData: CopyData|null = null; /** * Copy a block or workspace comment onto the local clipboard. + * * @param toCopy Block or Workspace Comment to be copied. * @alias Blockly.clipboard.copy * @internal @@ -29,6 +31,8 @@ export function copy(toCopy: ICopyable) { /** * Private version of copy for stubbing in tests. + * + * @param toCopy */ function copyInternal(toCopy: ICopyable) { copyData = toCopy.toCopyData(); @@ -36,7 +40,8 @@ function copyInternal(toCopy: ICopyable) { /** * Paste a block or workspace comment on to the main workspace. - * @return The pasted thing if the paste was successful, null otherwise. + * + * @returns The pasted thing if the paste was successful, null otherwise. * @alias Blockly.clipboard.paste * @internal */ @@ -59,8 +64,9 @@ export function paste(): ICopyable|null { /** * Duplicate this block and its children, or a workspace comment. + * * @param toDuplicate Block or Workspace Comment to be duplicated. - * @return The block or workspace comment that was duplicated, or null if the + * @returns The block or workspace comment that was duplicated, or null if the * duplication failed. * @alias Blockly.clipboard.duplicate * @internal @@ -71,6 +77,8 @@ export function duplicate(toDuplicate: ICopyable): ICopyable|null { /** * Private version of duplicate for stubbing in tests. + * + * @param toDuplicate */ function duplicateInternal(toDuplicate: ICopyable): ICopyable|null { const oldCopyData = copyData; diff --git a/core/common.ts b/core/common.ts index 6c0956da4..e94969775 100644 --- a/core/common.ts +++ b/core/common.ts @@ -7,6 +7,7 @@ /** * Common functions used both internally and externally, but which * must not be at the top level to avoid circular dependencies. + * * @namespace Blockly.common */ import * as goog from '../closure/goog/goog.js'; @@ -27,8 +28,9 @@ const WorkspaceDB_ = Object.create(null); /** * Find the workspace with the specified ID. + * * @param id ID of workspace to find. - * @return The sought after workspace or null if not found. + * @returns The sought after workspace or null if not found. */ export function getWorkspaceById(id: string): Workspace|null { return WorkspaceDB_[id] || null; @@ -36,7 +38,8 @@ export function getWorkspaceById(id: string): Workspace|null { /** * Find all workspaces. - * @return Array of workspaces. + * + * @returns Array of workspaces. */ export function getAllWorkspaces(): Workspace[] { const workspaces = []; @@ -46,10 +49,18 @@ export function getAllWorkspaces(): Workspace[] { return workspaces; } +/** + * + * @param workspace + */ export function registerWorkspace(workspace: Workspace) { WorkspaceDB_[workspace.id] = workspace; } +/** + * + * @param workspace + */ export function unregisterWorkpace(workspace: Workspace) { delete WorkspaceDB_[workspace.id]; } @@ -64,7 +75,8 @@ let mainWorkspace: Workspace; * Returns the last used top level workspace (based on focus). Try not to use * this function, particularly if there are multiple Blockly instances on a * page. - * @return The main workspace. + * + * @returns The main workspace. * @alias Blockly.common.getMainWorkspace */ export function getMainWorkspace(): Workspace { @@ -73,6 +85,7 @@ export function getMainWorkspace(): Workspace { /** * Sets last used main workspace. + * * @param workspace The most recently used top level workspace. * @alias Blockly.common.setMainWorkspace */ @@ -87,6 +100,7 @@ let selected: ICopyable|null = null; /** * Returns the currently selected copyable object. + * * @alias Blockly.common.getSelected */ export function getSelected(): ICopyable|null { @@ -97,6 +111,7 @@ export function getSelected(): ICopyable|null { * Sets the currently selected block. This function does not visually mark the * block as selected or fire the required events. If you wish to * programmatically select a block, use `BlockSvg#select`. + * * @param newSelection The newly selected block. * @alias Blockly.common.setSelected * @internal @@ -113,7 +128,8 @@ let parentContainer: Element|null; /** * Get the container element in which to render the WidgetDiv, DropDownDiv and\ * Tooltip. - * @return The parent container. + * + * @returns The parent container. * @alias Blockly.common.getParentContainer */ export function getParentContainer(): Element|null { @@ -125,6 +141,7 @@ export function getParentContainer(): Element|null { * DropDownDiv, and Tooltip are rendered into the first time `Blockly.inject` * is called. * This method is a NOP if called after the first ``Blockly.inject``. + * * @param newParent The container element. * @alias Blockly.common.setParentContainer */ @@ -138,6 +155,7 @@ export function setParentContainer(newParent: Element) { * See workspace.resizeContents to resize the workspace when the contents * change (e.g. when a block is added or removed). * Record the height/width of the SVG image. + * * @param workspace Any workspace in the SVG. * @alias Blockly.common.svgResize */ @@ -175,11 +193,12 @@ export const draggingConnections: Connection[] = []; /** * Get a map of all the block's descendants mapping their type to the number of * children with that type. + * * @param block The block to map. * @param opt_stripFollowing Optionally ignore all following * statements (blocks that are not inside a value or statement input * of the block). - * @return Map of types to type counts for descendants of the bock. + * @returns Map of types to type counts for descendants of the bock. * @alias Blockly.common.getBlockTypeCounts */ export function getBlockTypeCounts( @@ -206,8 +225,9 @@ export function getBlockTypeCounts( /** * Helper function for defining a block from JSON. The resulting function has * the correct value of jsonDef at the point in code where jsonInit is called. + * * @param jsonDef The JSON definition of a block. - * @return A function that calls jsonInit with the correct value + * @returns A function that calls jsonInit with the correct value * of jsonDef. */ function jsonInitFactory(jsonDef: AnyDuringMigration): () => void { @@ -219,6 +239,7 @@ function jsonInitFactory(jsonDef: AnyDuringMigration): () => void { /** * Define blocks from an array of JSON block definitions, as might be generated * by the Blockly Developer Tools. + * * @param jsonArray An array of JSON block definitions. * @alias Blockly.common.defineBlocksWithJsonArray */ @@ -228,6 +249,8 @@ export function defineBlocksWithJsonArray(jsonArray: AnyDuringMigration[]) { /** * Private version of defineBlocksWithJsonArray for stubbing in tests. + * + * @param jsonArray */ function defineBlocksWithJsonArrayInternal(jsonArray: AnyDuringMigration[]) { defineBlocks(createBlockDefinitionsFromJsonArray(jsonArray)); @@ -236,8 +259,9 @@ function defineBlocksWithJsonArrayInternal(jsonArray: AnyDuringMigration[]) { /** * Define blocks from an array of JSON block definitions, as might be generated * by the Blockly Developer Tools. + * * @param jsonArray An array of JSON block definitions. - * @return A map of the block + * @returns A map of the block * definitions created. * @alias Blockly.common.defineBlocksWithJsonArray */ @@ -265,6 +289,7 @@ export function createBlockDefinitionsFromJsonArray( /** * Add the specified block definitions to the block definitions * dictionary (Blockly.Blocks). + * * @param blocks A map of block * type names to block definitions. * @alias Blockly.common.defineBlocks diff --git a/core/component_manager.ts b/core/component_manager.ts index 4361e899e..8f303a245 100644 --- a/core/component_manager.ts +++ b/core/component_manager.ts @@ -6,6 +6,7 @@ /** * Manager for all items registered with the workspace. + * * @class */ import * as goog from '../closure/goog/goog.js'; @@ -32,7 +33,8 @@ class Capability<_T> { /** * Returns the name of the capability. - * @return The name. + * + * @returns The name. */ toString(): string { return this.name_; @@ -41,6 +43,7 @@ class Capability<_T> { /** * Manager for all items registered with the workspace. + * * @alias Blockly.ComponentManager */ export class ComponentManager { @@ -56,6 +59,7 @@ export class ComponentManager { /** * Adds a component. + * * @param componentInfo The data for the component to register. * @param opt_allowOverrides True to prevent an error when overriding an * already registered item. @@ -84,6 +88,7 @@ export class ComponentManager { /** * Removes a component. + * * @param id The ID of the component to remove. */ removeComponent(id: string) { @@ -100,6 +105,7 @@ export class ComponentManager { /** * Adds a capability to a existing registered component. + * * @param id The ID of the component to add the capability to. * @param capability The capability to add. */ @@ -121,6 +127,7 @@ export class ComponentManager { /** * Removes a capability from an existing registered component. + * * @param id The ID of the component to remove the capability from. * @param capability The capability to remove. */ @@ -143,9 +150,10 @@ export class ComponentManager { /** * Returns whether the component with this id has the specified capability. + * * @param id The ID of the component to check. * @param capability The capability to check for. - * @return Whether the component has the capability. + * @returns Whether the component has the capability. */ hasCapability(id: string, capability: string|Capability): boolean { capability = String(capability).toLowerCase(); @@ -155,8 +163,9 @@ export class ComponentManager { /** * Gets the component with the given ID. + * * @param id The ID of the component to get. - * @return The component with the given name or undefined if not found. + * @returns The component with the given name or undefined if not found. */ getComponent(id: string): IComponent|undefined { return this.componentData.get(id)?.component; @@ -164,9 +173,10 @@ export class ComponentManager { /** * Gets all the components with the specified capability. + * * @param capability The capability of the component. * @param sorted Whether to return list ordered by weights. - * @return The components that match the specified capability. + * @returns The components that match the specified capability. */ getComponents(capability: string|Capability, sorted: boolean): T[] { capability = String(capability).toLowerCase(); diff --git a/core/connection.ts b/core/connection.ts index e14da6d05..8520ac2f4 100644 --- a/core/connection.ts +++ b/core/connection.ts @@ -6,6 +6,7 @@ /** * Components for creating connections between blocks. + * * @class */ import * as goog from '../closure/goog/goog.js'; @@ -27,6 +28,7 @@ import * as Xml from './xml.js'; /** * Class for a connection between blocks. + * * @alias Blockly.Connection */ export class Connection implements IASTNodeLocationWithBlock { @@ -48,6 +50,7 @@ export class Connection implements IASTNodeLocationWithBlock { /** * Has this connection been disposed of? + * * @internal */ disposed = false; @@ -60,12 +63,14 @@ export class Connection implements IASTNodeLocationWithBlock { /** * Horizontal location of this connection. + * * @internal */ x = 0; /** * Vertical location of this connection. + * * @internal */ y = 0; @@ -83,6 +88,7 @@ export class Connection implements IASTNodeLocationWithBlock { /** * Connect two connections together. This is the connection on the superior * block. + * * @param childConnection Connection on inferior block. */ protected connect_(childConnection: Connection) { @@ -140,6 +146,7 @@ export class Connection implements IASTNodeLocationWithBlock { /** * Dispose of this connection and deal with connected blocks. + * * @internal */ dispose() { @@ -160,7 +167,8 @@ export class Connection implements IASTNodeLocationWithBlock { /** * Get the source block for this connection. - * @return The source block. + * + * @returns The source block. */ getSourceBlock(): Block { return this.sourceBlock_; @@ -169,7 +177,8 @@ export class Connection implements IASTNodeLocationWithBlock { /** * Does the connection belong to a superior block (higher in the source * stack)? - * @return True if connection faces down or right. + * + * @returns True if connection faces down or right. */ isSuperior(): boolean { return this.type === ConnectionType.INPUT_VALUE || @@ -178,7 +187,8 @@ export class Connection implements IASTNodeLocationWithBlock { /** * Is the connection connected? - * @return True if connection is connected to another connection. + * + * @returns True if connection is connected to another connection. */ isConnected(): boolean { return !!this.targetConnection; @@ -186,7 +196,8 @@ export class Connection implements IASTNodeLocationWithBlock { /** * Get the workspace's connection type checker object. - * @return The connection type checker for the source block's workspace. + * + * @returns The connection type checker for the source block's workspace. * @internal */ getConnectionChecker(): IConnectionChecker { @@ -196,6 +207,7 @@ export class Connection implements IASTNodeLocationWithBlock { /** * Called when an attempted connection fails. NOP by default (i.e. for * headless workspaces). + * * @param _otherConnection Connection that this connection failed to connect * to. * @internal @@ -205,8 +217,9 @@ export class Connection implements IASTNodeLocationWithBlock { /** * Connect this connection to another connection. + * * @param otherConnection Connection to connect to. - * @return Whether the the blocks are now connected or not. + * @returns Whether the the blocks are now connected or not. */ connect(otherConnection: Connection): boolean { if (this.targetConnection === otherConnection) { @@ -276,6 +289,7 @@ export class Connection implements IASTNodeLocationWithBlock { /** * Disconnect two blocks that are connected by this connection. + * * @param parentBlock The superior block. * @param childBlock The inferior block. */ @@ -307,7 +321,8 @@ export class Connection implements IASTNodeLocationWithBlock { /** * Returns the block that this connection connects to. - * @return The connected block or null if none is connected. + * + * @returns The connected block or null if none is connected. */ targetBlock(): Block|null { if (this.isConnected()) { @@ -332,9 +347,10 @@ export class Connection implements IASTNodeLocationWithBlock { /** * Change a connection's compatibility. + * * @param check Compatible value type or list of value types. Null if all * types are compatible. - * @return The connection being modified (to allow chaining). + * @returns The connection being modified (to allow chaining). */ setCheck(check: string|string[]|null): Connection { if (check) { @@ -351,7 +367,8 @@ export class Connection implements IASTNodeLocationWithBlock { /** * Get a connection's compatibility. - * @return List of compatible value types. + * + * @returns List of compatible value types. * Null if all types are compatible. */ getCheck(): string[]|null { @@ -360,6 +377,7 @@ export class Connection implements IASTNodeLocationWithBlock { /** * Changes the connection's shadow block. + * * @param shadowDom DOM representation of a block or null. */ setShadowDom(shadowDom: Element|null) { @@ -368,11 +386,12 @@ export class Connection implements IASTNodeLocationWithBlock { /** * Returns the xml representation of the connection's shadow block. + * * @param returnCurrent If true, and the shadow block is currently attached to * this connection, this serializes the state of that block and returns it * (so that field values are correct). Otherwise the saved shadowDom is * just returned. - * @return Shadow DOM representation of a block or null. + * @returns Shadow DOM representation of a block or null. */ getShadowDom(returnCurrent?: boolean): Element|null { return returnCurrent && this.targetBlock()!.isShadow() ? @@ -382,6 +401,7 @@ export class Connection implements IASTNodeLocationWithBlock { /** * Changes the connection's shadow block. + * * @param shadowState An state represetation of the block or null. */ setShadowState(shadowState: blocks.State|null) { @@ -391,11 +411,12 @@ export class Connection implements IASTNodeLocationWithBlock { /** * Returns the serialized object representation of the connection's shadow * block. + * * @param returnCurrent If true, and the shadow block is currently attached to * this connection, this serializes the state of that block and returns it * (so that field values are correct). Otherwise the saved state is just * returned. - * @return Serialized object representation of the block, or null. + * @returns Serialized object representation of the block, or null. */ getShadowState(returnCurrent?: boolean): blocks.State|null { if (returnCurrent && this.targetBlock() && this.targetBlock()!.isShadow()) { @@ -412,8 +433,9 @@ export class Connection implements IASTNodeLocationWithBlock { * and always return an empty list (the default). * {@link Blockly.RenderedConnection} overrides this behavior with a list * computed from the rendered positioning. + * * @param _maxLimit The maximum radius to another connection. - * @return List of connections. + * @returns List of connections. * @internal */ neighbours(_maxLimit: number): Connection[] { @@ -422,7 +444,8 @@ export class Connection implements IASTNodeLocationWithBlock { /** * Get the parent input of a connection. - * @return The input that the connection belongs to or null if no parent + * + * @returns The input that the connection belongs to or null if no parent * exists. * @internal */ @@ -441,7 +464,8 @@ export class Connection implements IASTNodeLocationWithBlock { /** * This method returns a string describing this Connection in developer terms * (English only). Intended to on be used in console logs and errors. - * @return The description. + * + * @returns The description. */ toString(): string { const block = this.sourceBlock_; @@ -476,7 +500,8 @@ export class Connection implements IASTNodeLocationWithBlock { /** * Returns the state of the shadowDom_ and shadowState_ properties, then * temporarily sets those properties to null so no shadow respawns. - * @return The state of both the shadowDom_ and shadowState_ properties. + * + * @returns The state of both the shadowDom_ and shadowState_ properties. */ private stashShadowState_(): {shadowDom: Element|null, shadowState: blocks.State|null} { @@ -490,8 +515,11 @@ export class Connection implements IASTNodeLocationWithBlock { /** * Reapplies the stashed state of the shadowDom_ and shadowState_ properties. + * * @param param0 The state to reapply to the shadowDom_ and shadowState_ * properties. + * @param param0.shadowDom + * @param param0.shadowState */ private applyShadowState_({shadowDom, shadowState}: { shadowDom: Element|null, @@ -503,7 +531,10 @@ export class Connection implements IASTNodeLocationWithBlock { /** * Sets the state of the shadow of this connection. + * * @param param0 The state to set the shadow of this connection to. + * @param param0.shadowDom + * @param param0.shadowState */ private setShadowStateInternal_({shadowDom = null, shadowState = null}: { shadowDom?: Element|null, @@ -538,9 +569,10 @@ export class Connection implements IASTNodeLocationWithBlock { /** * Creates a shadow block based on the current shadowState_ or shadowDom_. * shadowState_ gets priority. + * * @param attemptToConnect Whether to try to connect the shadow block to this * connection or not. - * @return The shadow block that was created, or null if both the shadowState_ + * @returns The shadow block that was created, or null if both the shadowState_ * and shadowDom_ are null. */ private createShadowBlock_(attemptToConnect: boolean): Block|null { @@ -591,6 +623,7 @@ export class Connection implements IASTNodeLocationWithBlock { /** * Saves the given shadow block to both the shadowDom_ and shadowState_ * properties, in their respective serialized forms. + * * @param shadow The shadow to serialize, or null. */ private serializeShadow_(shadow: Block|null) { @@ -605,9 +638,10 @@ export class Connection implements IASTNodeLocationWithBlock { * Returns the connection (starting at the startBlock) which will accept * the given connection. This includes compatible connection types and * connection checks. + * * @param startBlock The block on which to start the search. * @param orphanConnection The connection that is looking for a home. - * @return The suitable connection point on the chain of blocks, or null. + * @returns The suitable connection point on the chain of blocks, or null. */ static getConnectionForOrphanedConnection( startBlock: Block, orphanConnection: Connection): Connection|null { @@ -627,6 +661,7 @@ export class Connection implements IASTNodeLocationWithBlock { /** * Update two connections to target each other. + * * @param first The first connection to update. * @param second The second connection to update. */ @@ -642,9 +677,10 @@ function connectReciprocally(first: Connection, second: Connection) { * block, if one can be found. If the block has multiple compatible connections * (even if they are filled) this returns null. If the block has no compatible * connections, this returns null. + * * @param block The superior block. * @param orphanBlock The inferior block. - * @return The suitable connection point on 'block', or null. + * @returns The suitable connection point on 'block', or null. */ function getSingleConnection(block: Block, orphanBlock: Block): Connection| null { @@ -670,9 +706,10 @@ function getSingleConnection(block: Block, orphanBlock: Block): Connection| * are zero or multiple eligible connections, returns null. Otherwise * returns the only input on the last block in the chain. * Terminates early for shadow blocks. + * * @param startBlock The block on which to start the search. * @param orphanBlock The block that is looking for a home. - * @return The suitable connection point on the chain of blocks, or null. + * @returns The suitable connection point on the chain of blocks, or null. */ function getConnectionForOrphanedOutput( startBlock: Block, orphanBlock: Block): Connection|null { diff --git a/core/connection_checker.ts b/core/connection_checker.ts index e2031262b..ccb54f539 100644 --- a/core/connection_checker.ts +++ b/core/connection_checker.ts @@ -7,6 +7,7 @@ /** * An object that encapsulates logic for checking whether a * potential connection is safe and valid. + * * @class */ import * as goog from '../closure/goog/goog.js'; @@ -23,18 +24,20 @@ import type {RenderedConnection} from './rendered_connection.js'; /** * Class for connection type checking logic. + * * @alias Blockly.ConnectionChecker */ export class ConnectionChecker implements IConnectionChecker { /** * Check whether the current connection can connect with the target * connection. + * * @param a Connection to check compatibility with. * @param b Connection to check compatibility with. * @param isDragging True if the connection is being made by dragging a block. * @param opt_distance The max allowable distance between the connections for * drag checks. - * @return Whether the connection is legal. + * @returns Whether the connection is legal. */ canConnect( a: Connection|null, b: Connection|null, isDragging: boolean, @@ -46,12 +49,13 @@ export class ConnectionChecker implements IConnectionChecker { /** * Checks whether the current connection can connect with the target * connection, and return an error code if there are problems. + * * @param a Connection to check compatibility with. * @param b Connection to check compatibility with. * @param isDragging True if the connection is being made by dragging a block. * @param opt_distance The max allowable distance between the connections for * drag checks. - * @return Connection.CAN_CONNECT if the connection is legal, an error code + * @returns Connection.CAN_CONNECT if the connection is legal, an error code * otherwise. */ canConnectWithReason( @@ -81,10 +85,11 @@ export class ConnectionChecker implements IConnectionChecker { /** * Helper method that translates a connection error code into a string. + * * @param errorCode The error code. * @param a One of the two connections being checked. * @param b The second of the two connections being checked. - * @return A developer-readable error string. + * @returns A developer-readable error string. */ getErrorMessage(errorCode: number, a: Connection|null, b: Connection|null): string { @@ -120,9 +125,10 @@ export class ConnectionChecker implements IConnectionChecker { /** * Check that connecting the given connections is safe, meaning that it would * not break any of Blockly's basic assumptions (e.g. no self connections). + * * @param a The first of the connections to check. * @param b The second of the connections to check. - * @return An enum with the reason this connection is safe or unsafe. + * @returns An enum with the reason this connection is safe or unsafe. */ doSafetyChecks(a: Connection|null, b: Connection|null): number { if (!a || !b) { @@ -171,9 +177,10 @@ export class ConnectionChecker implements IConnectionChecker { * Check whether this connection is compatible with another connection with * respect to the value type system. E.g. square_root("Hello") is not * compatible. + * * @param a Connection to compare. * @param b Connection to compare against. - * @return True if the connections share a type. + * @returns True if the connections share a type. */ doTypeChecks(a: Connection, b: Connection): boolean { const checkArrayOne = a.getCheck(); @@ -195,10 +202,11 @@ export class ConnectionChecker implements IConnectionChecker { /** * Check whether this connection can be made by dragging. + * * @param a Connection to compare. * @param b Connection to compare against. * @param distance The maximum allowable distance between connections. - * @return True if the connection is allowed during a drag. + * @returns True if the connection is allowed during a drag. */ doDragChecks(a: RenderedConnection, b: RenderedConnection, distance: number): boolean { @@ -259,10 +267,11 @@ export class ConnectionChecker implements IConnectionChecker { /** * Helper function for drag checking. + * * @param a The connection to check, which must be a statement input or next * connection. * @param b A nearby connection to check, which must be a previous connection. - * @return True if the connection is allowed, false otherwise. + * @returns True if the connection is allowed, false otherwise. */ protected canConnectToPrevious_(a: Connection, b: Connection): boolean { if (a.targetConnection) { diff --git a/core/connection_type.ts b/core/connection_type.ts index 1ad69a135..4e2d123f9 100644 --- a/core/connection_type.ts +++ b/core/connection_type.ts @@ -6,6 +6,7 @@ /** * An enum for the possible types of connections. + * * @namespace Blockly.ConnectionType */ import * as goog from '../closure/goog/goog.js'; @@ -14,6 +15,7 @@ goog.declareModuleId('Blockly.ConnectionType'); /** * Enum for the type of a connection or input. + * * @alias Blockly.ConnectionType */ export enum ConnectionType { diff --git a/core/constants.ts b/core/constants.ts index ad68d938a..68e807a21 100644 --- a/core/constants.ts +++ b/core/constants.ts @@ -6,6 +6,7 @@ /** * Blockly constants. + * * @namespace Blockly.constants */ import * as goog from '../closure/goog/goog.js'; @@ -14,12 +15,14 @@ goog.declareModuleId('Blockly.constants'); /** * The language-neutral ID given to the collapsed input. + * * @alias Blockly.constants.COLLAPSED_INPUT_NAME */ export const COLLAPSED_INPUT_NAME = '_TEMP_COLLAPSED_INPUT'; /** * The language-neutral ID given to the collapsed field. + * * @alias Blockly.constants.COLLAPSED_FIELD_NAME */ export const COLLAPSED_FIELD_NAME = '_TEMP_COLLAPSED_FIELD'; diff --git a/core/contextmenu_items.ts b/core/contextmenu_items.ts index cc3a3748c..00a59e9cd 100644 --- a/core/contextmenu_items.ts +++ b/core/contextmenu_items.ts @@ -6,6 +6,7 @@ /** * Registers default context menu items. + * * @namespace Blockly.ContextMenuItems */ import * as goog from '../closure/goog/goog.js'; @@ -26,6 +27,7 @@ import type {WorkspaceSvg} from './workspace_svg.js'; /** * Option to undo previous action. + * * @alias Blockly.ContextMenuItems.registerUndo */ export function registerUndo() { @@ -51,6 +53,7 @@ export function registerUndo() { /** * Option to redo previous action. + * * @alias Blockly.ContextMenuItems.registerRedo */ export function registerRedo() { @@ -76,6 +79,7 @@ export function registerRedo() { /** * Option to clean up blocks. + * * @alias Blockly.ContextMenuItems.registerCleanup */ export function registerCleanup() { @@ -103,6 +107,7 @@ export function registerCleanup() { } /** * Creates a callback to collapse or expand top blocks. + * * @param shouldCollapse Whether a block should collapse. * @param topBlocks Top blocks in the workspace. */ @@ -110,6 +115,10 @@ function toggleOption_(shouldCollapse: boolean, topBlocks: BlockSvg[]) { const DELAY = 10; let ms = 0; let timeoutCounter = 0; + /** + * + * @param block + */ function timeoutFn(block: BlockSvg) { timeoutCounter--; block.setCollapsed(shouldCollapse); @@ -131,6 +140,7 @@ function toggleOption_(shouldCollapse: boolean, topBlocks: BlockSvg[]) { /** * Option to collapse all blocks. + * * @alias Blockly.ContextMenuItems.registerCollapse */ export function registerCollapse() { @@ -166,6 +176,7 @@ export function registerCollapse() { /** * Option to expand all blocks. + * * @alias Blockly.ContextMenuItems.registerExpand */ export function registerExpand() { @@ -200,6 +211,7 @@ export function registerExpand() { } /** * Adds a block and its children to a list of deletable blocks. + * * @param block to delete. * @param deleteList list of blocks that can be deleted. * This will be modified in place with the given block and its descendants. @@ -217,8 +229,9 @@ function addDeletableBlocks_(block: BlockSvg, deleteList: BlockSvg[]) { /** * Constructs a list of blocks that can be deleted in the given workspace. + * * @param workspace to delete all blocks from. - * @return list of blocks to delete. + * @returns list of blocks to delete. */ function getDeletableBlocks_(workspace: WorkspaceSvg): BlockSvg[] { const deleteList: BlockSvg[] = []; @@ -231,6 +244,7 @@ function getDeletableBlocks_(workspace: WorkspaceSvg): BlockSvg[] { /** * Deletes the given blocks. Used to delete all blocks in the workspace. + * * @param deleteList list of blocks to delete. * @param eventGroup event group ID with which all delete events should be * associated. @@ -252,6 +266,7 @@ function deleteNext_(deleteList: BlockSvg[], eventGroup: string) { /** * Option to delete all blocks. + * * @alias Blockly.ContextMenuItems.registerDeleteAll */ export function registerDeleteAll() { @@ -313,6 +328,7 @@ function registerWorkspaceOptions_() { /** * Option to duplicate a block. + * * @alias Blockly.ContextMenuItems.registerDuplicate */ export function registerDuplicate() { @@ -344,6 +360,7 @@ export function registerDuplicate() { /** * Option to add or remove block-level comment. + * * @alias Blockly.ContextMenuItems.registerComment */ export function registerComment() { @@ -383,6 +400,7 @@ export function registerComment() { /** * Option to inline variables. + * * @alias Blockly.ContextMenuItems.registerInline */ export function registerInline() { @@ -417,6 +435,7 @@ export function registerInline() { /** * Option to collapse or expand a block. + * * @alias Blockly.ContextMenuItems.registerCollapseExpandBlock */ export function registerCollapseExpandBlock() { @@ -445,6 +464,7 @@ export function registerCollapseExpandBlock() { /** * Option to disable or enable a block. + * * @alias Blockly.ContextMenuItems.registerDisable */ export function registerDisable() { @@ -484,6 +504,7 @@ export function registerDisable() { /** * Option to delete a block. + * * @alias Blockly.ContextMenuItems.registerDelete */ export function registerDelete() { @@ -521,6 +542,7 @@ export function registerDelete() { /** * Option to open help for a block. + * * @alias Blockly.ContextMenuItems.registerHelp */ export function registerHelp() { @@ -561,6 +583,7 @@ function registerBlockOptions_() { /** * Registers all default context menu items. This should be called once per * instance of ContextMenuRegistry. + * * @alias Blockly.ContextMenuItems.registerDefaultOptions * @internal */ diff --git a/core/contextmenu_registry.ts b/core/contextmenu_registry.ts index ff763500a..44c2dc84b 100644 --- a/core/contextmenu_registry.ts +++ b/core/contextmenu_registry.ts @@ -6,6 +6,7 @@ /** * Registry for context menu option items. + * * @class */ import * as goog from '../closure/goog/goog.js'; @@ -19,6 +20,7 @@ import type {WorkspaceSvg} from './workspace_svg.js'; * Class for the registry of context menu items. This is intended to be a * singleton. You should not create a new instance, and only access this class * from ContextMenuRegistry.registry. + * * @alias Blockly.ContextMenuRegistry */ export class ContextMenuRegistry { @@ -38,6 +40,7 @@ export class ContextMenuRegistry { /** * Registers a RegistryItem. + * * @param item Context menu item to register. * @throws {Error} if an item with the given ID already exists. */ @@ -50,6 +53,7 @@ export class ContextMenuRegistry { /** * Unregisters a RegistryItem with the given ID. + * * @param id The ID of the RegistryItem to remove. * @throws {Error} if an item with the given ID does not exist. */ @@ -62,7 +66,7 @@ export class ContextMenuRegistry { /** * @param id The ID of the RegistryItem to get. - * @return RegistryItem or null if not found + * @returns RegistryItem or null if not found */ getItem(id: string): RegistryItem|null { return this.registry_.get(id) ?? null; @@ -72,11 +76,12 @@ export class ContextMenuRegistry { * Gets the valid context menu options for the given scope type (e.g. block or * workspace) and scope. Blocks are only shown if the preconditionFn shows * they should not be hidden. + * * @param scopeType Type of scope where menu should be shown (e.g. on a block * or on a workspace) * @param scope Current scope of context menu (i.e., the exact workspace or * block being clicked on) - * @return the list of ContextMenuOptions + * @returns the list of ContextMenuOptions */ getContextMenuOptions(scopeType: ScopeType, scope: Scope): ContextMenuOption[] { diff --git a/core/delete_area.ts b/core/delete_area.ts index e57194255..9bee66742 100644 --- a/core/delete_area.ts +++ b/core/delete_area.ts @@ -7,6 +7,7 @@ /** * The abstract class for a component that can delete a block or * bubble that is dropped on top of it. + * * @class */ import * as goog from '../closure/goog/goog.js'; @@ -21,6 +22,7 @@ import type {IDraggable} from './interfaces/i_draggable.js'; /** * Abstract class for a component that can delete a block or bubble that is * dropped on top of it. + * * @alias Blockly.DeleteArea */ export class DeleteArea extends DragTarget implements IDeleteArea { @@ -51,9 +53,10 @@ export class DeleteArea extends DragTarget implements IDeleteArea { * this area. * This method should check if the element is deletable and is always called * before onDragEnter/onDragOver/onDragExit. + * * @param element The block or bubble currently being dragged. * @param couldConnect Whether the element could could connect to another. - * @return Whether the element provided would be deleted if dropped on this + * @returns Whether the element provided would be deleted if dropped on this * area. */ wouldDelete(element: IDraggable, couldConnect: boolean): boolean { @@ -69,6 +72,7 @@ export class DeleteArea extends DragTarget implements IDeleteArea { /** * Updates the internal wouldDelete_ state. + * * @param wouldDelete The new value for the wouldDelete state. */ protected updateWouldDelete_(wouldDelete: boolean) { diff --git a/core/dialog.ts b/core/dialog.ts index 2518e7a60..61cf79ba1 100644 --- a/core/dialog.ts +++ b/core/dialog.ts @@ -6,6 +6,7 @@ /** * Wrapper functions around JS functions for showing alert/confirmation dialogs. + * * @namespace Blockly.dialog */ import * as goog from '../closure/goog/goog.js'; @@ -34,6 +35,7 @@ let promptImplementation = function( /** * Wrapper to window.alert() that app developers may override via setAlert to * provide alternatives to the modal browser window. + * * @param message The message to display to the user. * @param opt_callback The callback when the alert is dismissed. * @alias Blockly.dialog.alert @@ -45,6 +47,7 @@ export function alert( /** * Sets the function to be run when Blockly.dialog.alert() is called. + * * @param alertFunction The function to be run. * @see Blockly.dialog.alert * @alias Blockly.dialog.setAlert @@ -58,6 +61,7 @@ export function setAlert( /** * Wrapper to window.confirm() that app developers may override via setConfirm * to provide alternatives to the modal browser window. + * * @param message The message to display to the user. * @param callback The callback for handling user response. * @alias Blockly.dialog.confirm @@ -69,6 +73,9 @@ export function confirm( /** * Private version of confirm for stubbing in tests. + * + * @param message + * @param callback */ function confirmInternal( message: string, callback: (p1: boolean) => AnyDuringMigration) { @@ -78,6 +85,7 @@ function confirmInternal( /** * Sets the function to be run when Blockly.dialog.confirm() is called. + * * @param confirmFunction The function to be run. * @see Blockly.dialog.confirm * @alias Blockly.dialog.setConfirm @@ -93,6 +101,7 @@ export function setConfirm( * 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. + * * @param message The message to display to the user. * @param defaultValue The value to initialize the prompt with. * @param callback The callback for handling user response. @@ -106,6 +115,7 @@ export function prompt( /** * Sets the function to be run when Blockly.dialog.prompt() is called. + * * @param promptFunction The function to be run. * @see Blockly.dialog.prompt * @alias Blockly.dialog.setPrompt diff --git a/core/drag_target.ts b/core/drag_target.ts index 996c42519..a8977bca2 100644 --- a/core/drag_target.ts +++ b/core/drag_target.ts @@ -7,6 +7,7 @@ /** * The abstract class for a component with custom behaviour when a * block or bubble is dragged over or dropped on top of it. + * * @class */ import * as goog from '../closure/goog/goog.js'; @@ -20,6 +21,7 @@ import type {Rect} from './utils/rect.js'; /** * Abstract class for a component with custom behaviour when a block or bubble * is dragged over or dropped on top of it. + * * @alias Blockly.DragTarget */ export class DragTarget implements IDragTarget { @@ -38,6 +40,7 @@ export class DragTarget implements IDragTarget { /** * Handles when a cursor with a block or bubble enters this drag target. + * * @param _dragElement The block or bubble currently being dragged. */ onDragEnter(_dragElement: IDraggable) {} @@ -46,6 +49,7 @@ export class DragTarget implements IDragTarget { /** * Handles when a cursor with a block or bubble is dragged over this drag * target. + * * @param _dragElement The block or bubble currently being dragged. */ onDragOver(_dragElement: IDraggable) {} @@ -53,6 +57,7 @@ export class DragTarget implements IDragTarget { /** * Handles when a cursor with a block or bubble exits this drag target. + * * @param _dragElement The block or bubble currently being dragged. */ onDragExit(_dragElement: IDraggable) {} @@ -60,6 +65,7 @@ export class DragTarget implements IDragTarget { /** * Handles when a block or bubble is dropped on this component. * Should not handle delete here. + * * @param _dragElement The block or bubble currently being dragged. */ onDrop(_dragElement: IDraggable) {} @@ -68,7 +74,8 @@ export class DragTarget implements IDragTarget { /** * Returns the bounding rectangle of the drag target area in pixel units * relative to the Blockly injection div. - * @return The component's bounding box. Null if drag target area should be + * + * @returns The component's bounding box. Null if drag target area should be * ignored. */ getClientRect(): Rect|null { @@ -79,8 +86,9 @@ export class DragTarget implements IDragTarget { * Returns whether the provided block or bubble should not be moved after * being dropped on this component. If true, the element will return to where * it was when the drag started. + * * @param _dragElement The block or bubble currently being dragged. - * @return Whether the block or bubble provided should be returned to drag + * @returns Whether the block or bubble provided should be returned to drag * start. */ shouldPreventMove(_dragElement: IDraggable): boolean { diff --git a/core/dropdowndiv.ts b/core/dropdowndiv.ts index 1a7abbb53..a6ae967d8 100644 --- a/core/dropdowndiv.ts +++ b/core/dropdowndiv.ts @@ -7,6 +7,7 @@ /** * A div that floats on top of the workspace, for drop-down menus. + * * @class */ import * as goog from '../closure/goog/goog.js'; @@ -110,6 +111,7 @@ export interface PositionMetrics { /** * Create and insert the DOM element for this div. + * * @internal */ export function createDom() { @@ -149,6 +151,7 @@ export function createDom() { /** * Set an element to maintain bounds within. Drop-downs will appear * within the box of this element if possible. + * * @param boundsElem Element to bind drop-down to. */ export function setBoundsElement(boundsElem: Element|null) { @@ -157,7 +160,8 @@ export function setBoundsElement(boundsElem: Element|null) { /** * Provide the div for inserting content into the drop-down. - * @return Div to populate with content. + * + * @returns Div to populate with content. */ export function getContentDiv(): Element { return content; @@ -171,6 +175,7 @@ export function clearContent() { /** * Set the colour for the drop-down. + * * @param backgroundColour Any CSS colour for the background. * @param borderColour Any CSS colour for the border. */ @@ -184,11 +189,12 @@ export function setColour(backgroundColour: string, borderColour: string) { * by a particular block. The primary position will be below the block, * and the secondary position above the block. Drop-down will be * constrained to the block's workspace. + * * @param field The field showing the drop-down. * @param block Block to position the drop-down around. * @param opt_onHide Optional callback for when the drop-down is hidden. * @param opt_secondaryYOffset Optional Y offset for above-block positioning. - * @return True if the menu rendered below block; false if above. + * @returns True if the menu rendered below block; false if above. */ export function showPositionedByBlock( field: Field, block: BlockSvg, opt_onHide?: Function, @@ -202,10 +208,11 @@ export function showPositionedByBlock( * by a particular field. The primary position will be below the field, * and the secondary position above the field. Drop-down will be * constrained to the block's workspace. + * * @param field The field to position the dropdown against. * @param opt_onHide Optional callback for when the drop-down is hidden. * @param opt_secondaryYOffset Optional Y offset for above-block positioning. - * @return True if the menu rendered below block; false if above. + * @returns True if the menu rendered below block; false if above. */ export function showPositionedByField( field: Field, opt_onHide?: Function, @@ -216,8 +223,9 @@ export function showPositionedByField( } /** * Get the scaled bounding box of a block. + * * @param block The block. - * @return The scaled bounding box of the block. + * @returns The scaled bounding box of the block. */ function getScaledBboxOfBlock(block: BlockSvg): Rect { const blockSvg = block.getSvgRoot(); @@ -230,8 +238,9 @@ function getScaledBboxOfBlock(block: BlockSvg): Rect { /** * Get the scaled bounding box of a field. + * * @param field The field. - * @return The scaled bounding box of the field. + * @returns The scaled bounding box of the field. */ function getScaledBboxOfField(field: Field): Rect { const bBox = field.getScaledBBox(); @@ -243,11 +252,12 @@ function getScaledBboxOfField(field: Field): Rect { * by a scaled bounding box. The primary position will be below the rect, * and the secondary position above the rect. Drop-down will be constrained to * the block's workspace. + * * @param bBox The scaled bounding box. * @param field The field to position the dropdown against. * @param opt_onHide Optional callback for when the drop-down is hidden. * @param opt_secondaryYOffset Optional Y offset for above-block positioning. - * @return True if the menu rendered below block; false if above. + * @returns True if the menu rendered below block; false if above. */ function showPositionedByRect( bBox: Rect, field: Field, opt_onHide?: Function, @@ -281,6 +291,7 @@ function showPositionedByRect( * will point there, and the container will be positioned below it. * If we can't maintain the container bounds at the primary point, fall-back to * the secondary point and position above. + * * @param newOwner The object showing the drop-down * @param rtl Right-to-left (true) or left-to-right (false). * @param primaryX Desired origin point x, in absolute px. @@ -288,7 +299,7 @@ function showPositionedByRect( * @param secondaryX Secondary/alternative origin point x, in absolute px. * @param secondaryY Secondary/alternative origin point y, in absolute px. * @param opt_onHide Optional callback for when the drop-down is hidden. - * @return True if the menu rendered at the primary origin point. + * @returns True if the menu rendered at the primary origin point. * @internal */ export function show( @@ -321,7 +332,8 @@ const internal = {}; /** * Get sizing info about the bounding element. - * @return An object containing size information about the bounding element + * + * @returns An object containing size information about the bounding element * (bounding box and width/height). */ // AnyDuringMigration because: Property 'getBoundsInfo' does not exist on type @@ -343,11 +355,12 @@ const internal = {}; /** * Helper to position the drop-down and the arrow, maintaining bounds. * See explanation of origin points in show. + * * @param primaryX Desired origin point x, in absolute px. * @param primaryY Desired origin point y, in absolute px. * @param secondaryX Secondary/alternative origin point x, in absolute px. * @param secondaryY Secondary/alternative origin point y, in absolute px. - * @return Various final metrics, including rendered positions for drop-down and + * @returns Various final metrics, including rendered positions for drop-down and * arrow. */ // AnyDuringMigration because: Property 'getPositionMetrics' does not exist on @@ -383,13 +396,14 @@ const internal = {}; /** * Get the metrics for positioning the div below the source. + * * @param primaryX Desired origin point x, in absolute px. * @param primaryY Desired origin point y, in absolute px. * @param boundsInfo An object containing size information about the bounding * element (bounding box and width/height). * @param divSize An object containing information about the size of the * DropDownDiv (width & height). - * @return Various final metrics, including rendered positions for drop-down and + * @returns Various final metrics, including rendered positions for drop-down and * arrow. */ function getPositionBelowMetrics( @@ -415,13 +429,14 @@ function getPositionBelowMetrics( /** * Get the metrics for positioning the div above the source. + * * @param secondaryX Secondary/alternative origin point x, in absolute px. * @param secondaryY Secondary/alternative origin point y, in absolute px. * @param boundsInfo An object containing size information about the bounding * element (bounding box and width/height). * @param divSize An object containing information about the size of the * DropDownDiv (width & height). - * @return Various final metrics, including rendered positions for drop-down and + * @returns Various final metrics, including rendered positions for drop-down and * arrow. */ function getPositionAboveMetrics( @@ -448,12 +463,13 @@ function getPositionAboveMetrics( /** * Get the metrics for positioning the div at the top of the page. + * * @param sourceX Desired origin point x, in absolute px. * @param boundsInfo An object containing size information about the bounding * element (bounding box and width/height). * @param divSize An object containing information about the size of the * DropDownDiv (width & height). - * @return Various final metrics, including rendered positions for drop-down and + * @returns Various final metrics, including rendered positions for drop-down and * arrow. */ function getPositionTopOfPageMetrics( @@ -477,11 +493,12 @@ function getPositionTopOfPageMetrics( /** * Get the x positions for the left side of the DropDownDiv and the arrow, * accounting for the bounds of the workspace. + * * @param sourceX Desired origin point x, in absolute px. * @param boundsLeft The left edge of the bounding element, in absolute px. * @param boundsRight The right edge of the bounding element, in absolute px. * @param divWidth The width of the div in px. - * @return An object containing metrics for the x positions of the left side of + * @returns An object containing metrics for the x positions of the left side of * the DropDownDiv and the arrow. * @internal */ @@ -509,7 +526,8 @@ export function getPositionX( /** * Is the container visible? - * @return True if visible. + * + * @returns True if visible. */ export function isVisible(): boolean { return !!owner; @@ -517,10 +535,11 @@ export function isVisible(): boolean { /** * Hide the menu only if it is owned by the provided object. + * * @param divOwner Object which must be owning the drop-down to hide. * @param opt_withoutAnimation True if we should hide the dropdown without * animating. - * @return True if hidden. + * @returns True if hidden. */ export function hideIfOwner( divOwner: AnyDuringMigration|null, @@ -595,11 +614,12 @@ export function hideWithoutAnimation() { /** * Set the dropdown div's position. + * * @param primaryX Desired origin point x, in absolute px. * @param primaryY Desired origin point y, in absolute px. * @param secondaryX Secondary/alternative origin point x, in absolute px. * @param secondaryY Secondary/alternative origin point y, in absolute px. - * @return True if the menu rendered at the primary origin point. + * @returns True if the menu rendered at the primary origin point. */ function positionInternal( primaryX: number, primaryY: number, secondaryX: number, @@ -650,6 +670,7 @@ function positionInternal( /** * Repositions the dropdownDiv on window resize. If it doesn't know how to * calculate the new position, it will just hide it instead. + * * @internal */ export function repositionForWindowResize() { diff --git a/core/events/events_block_drag.ts b/core/events/events_block_drag.ts index 313bf7058..41b9a3bf1 100644 --- a/core/events/events_block_drag.ts +++ b/core/events/events_block_drag.ts @@ -6,6 +6,7 @@ /** * Events fired as a block drag. + * * @class */ import * as goog from '../../closure/goog/goog.js'; @@ -20,6 +21,7 @@ import * as eventUtils from './utils.js'; /** * Class for a block drag event. + * * @alias Blockly.Events.BlockDrag */ export class BlockDrag extends UiBase { @@ -53,7 +55,8 @@ export class BlockDrag extends UiBase { /** * Encode the event as JSON. - * @return JSON representation. + * + * @returns JSON representation. */ override toJson(): AnyDuringMigration { const json = super.toJson(); @@ -65,6 +68,7 @@ export class BlockDrag extends UiBase { /** * Decode the JSON event. + * * @param json JSON representation. */ override fromJson(json: AnyDuringMigration) { diff --git a/core/events/events_theme_change.ts b/core/events/events_theme_change.ts index a318a7a18..811b69ab0 100644 --- a/core/events/events_theme_change.ts +++ b/core/events/events_theme_change.ts @@ -6,6 +6,7 @@ /** * Events fired as a result of a theme update. + * * @class */ import * as goog from '../../closure/goog/goog.js'; @@ -19,6 +20,7 @@ import * as eventUtils from './utils.js'; /** * Class for a theme change event. + * * @alias Blockly.Events.ThemeChange */ export class ThemeChange extends UiBase { @@ -42,7 +44,8 @@ export class ThemeChange extends UiBase { /** * Encode the event as JSON. - * @return JSON representation. + * + * @returns JSON representation. */ override toJson(): AnyDuringMigration { const json = super.toJson(); @@ -52,6 +55,7 @@ export class ThemeChange extends UiBase { /** * Decode the JSON event. + * * @param json JSON representation. */ override fromJson(json: AnyDuringMigration) { diff --git a/core/events/events_toolbox_item_select.ts b/core/events/events_toolbox_item_select.ts index 6b26b3d3b..6983d5886 100644 --- a/core/events/events_toolbox_item_select.ts +++ b/core/events/events_toolbox_item_select.ts @@ -6,6 +6,7 @@ /** * Events fired as a result of selecting an item on the toolbox. + * * @class */ import * as goog from '../../closure/goog/goog.js'; @@ -19,6 +20,7 @@ import * as eventUtils from './utils.js'; /** * Class for a toolbox item select event. + * * @alias Blockly.Events.ToolboxItemSelect */ export class ToolboxItemSelect extends UiBase { @@ -51,7 +53,8 @@ export class ToolboxItemSelect extends UiBase { /** * Encode the event as JSON. - * @return JSON representation. + * + * @returns JSON representation. */ override toJson(): AnyDuringMigration { const json = super.toJson(); @@ -62,6 +65,7 @@ export class ToolboxItemSelect extends UiBase { /** * Decode the JSON event. + * * @param json JSON representation. */ override fromJson(json: AnyDuringMigration) { diff --git a/core/events/utils.ts b/core/events/utils.ts index 2dea56a3f..b0bd7cf97 100644 --- a/core/events/utils.ts +++ b/core/events/utils.ts @@ -7,6 +7,7 @@ /** * Helper methods for events that are fired as a result of * actions in Blockly's editor. + * * @namespace Blockly.Events.utils */ import * as goog from '../../closure/goog/goog.js'; @@ -36,6 +37,7 @@ let recordUndo = true; /** * Sets whether events should be added to the undo stack. + * * @param newValue True if events should be added to the undo stack. * @alias Blockly.Events.utils.setRecordUndo */ @@ -45,6 +47,7 @@ export function setRecordUndo(newValue: boolean) { /** * Returns whether or not events will be added to the undo stack. + * * @returns True if events will be added to the undo stack. * @alias Blockly.Events.utils.getRecordUndo */ @@ -57,156 +60,182 @@ let disabled = 0; /** * Name of event that creates a block. Will be deprecated for BLOCK_CREATE. + * * @alias Blockly.Events.utils.CREATE */ export const CREATE = 'create'; /** * Name of event that creates a block. + * * @alias Blockly.Events.utils.BLOCK_CREATE */ export const BLOCK_CREATE = CREATE; /** * Name of event that deletes a block. Will be deprecated for BLOCK_DELETE. + * * @alias Blockly.Events.utils.DELETE */ export const DELETE = 'delete'; /** * Name of event that deletes a block. + * * @alias Blockly.Events.utils.BLOCK_DELETE */ export const BLOCK_DELETE = DELETE; /** * Name of event that changes a block. Will be deprecated for BLOCK_CHANGE. + * * @alias Blockly.Events.utils.CHANGE */ export const CHANGE = 'change'; /** * Name of event that changes a block. + * * @alias Blockly.Events.utils.BLOCK_CHANGE */ export const BLOCK_CHANGE = CHANGE; /** * Name of event that moves a block. Will be deprecated for BLOCK_MOVE. + * * @alias Blockly.Events.utils.MOVE */ export const MOVE = 'move'; /** * Name of event that moves a block. + * * @alias Blockly.Events.utils.BLOCK_MOVE */ export const BLOCK_MOVE = MOVE; /** * Name of event that creates a variable. + * * @alias Blockly.Events.utils.VAR_CREATE */ export const VAR_CREATE = 'var_create'; /** * Name of event that deletes a variable. + * * @alias Blockly.Events.utils.VAR_DELETE */ export const VAR_DELETE = 'var_delete'; /** * Name of event that renames a variable. + * * @alias Blockly.Events.utils.VAR_RENAME */ export const VAR_RENAME = 'var_rename'; /** * Name of generic event that records a UI change. + * * @alias Blockly.Events.utils.UI */ export const UI = 'ui'; /** * Name of event that record a block drags a block. + * * @alias Blockly.Events.utils.BLOCK_DRAG */ export const BLOCK_DRAG = 'drag'; /** * Name of event that records a change in selected element. + * * @alias Blockly.Events.utils.SELECTED */ export const SELECTED = 'selected'; /** * Name of event that records a click. + * * @alias Blockly.Events.utils.CLICK */ export const CLICK = 'click'; /** * Name of event that records a marker move. + * * @alias Blockly.Events.utils.MARKER_MOVE */ export const MARKER_MOVE = 'marker_move'; /** * Name of event that records a bubble open. + * * @alias Blockly.Events.utils.BUBBLE_OPEN */ export const BUBBLE_OPEN = 'bubble_open'; /** * Name of event that records a trashcan open. + * * @alias Blockly.Events.utils.TRASHCAN_OPEN */ export const TRASHCAN_OPEN = 'trashcan_open'; /** * Name of event that records a toolbox item select. + * * @alias Blockly.Events.utils.TOOLBOX_ITEM_SELECT */ export const TOOLBOX_ITEM_SELECT = 'toolbox_item_select'; /** * Name of event that records a theme change. + * * @alias Blockly.Events.utils.THEME_CHANGE */ export const THEME_CHANGE = 'theme_change'; /** * Name of event that records a viewport change. + * * @alias Blockly.Events.utils.VIEWPORT_CHANGE */ export const VIEWPORT_CHANGE = 'viewport_change'; /** * Name of event that creates a comment. + * * @alias Blockly.Events.utils.COMMENT_CREATE */ export const COMMENT_CREATE = 'comment_create'; /** * Name of event that deletes a comment. + * * @alias Blockly.Events.utils.COMMENT_DELETE */ export const COMMENT_DELETE = 'comment_delete'; /** * Name of event that changes a comment. + * * @alias Blockly.Events.utils.COMMENT_CHANGE */ export const COMMENT_CHANGE = 'comment_change'; /** * Name of event that moves a comment. + * * @alias Blockly.Events.utils.COMMENT_MOVE */ export const COMMENT_MOVE = 'comment_move'; /** * Name of event that records a workspace load. + * * @alias Blockly.Events.utils.FINISHED_LOADING */ export const FINISHED_LOADING = 'finished_loading'; @@ -217,6 +246,7 @@ export const FINISHED_LOADING = 'finished_loading'; * * Not to be confused with bumping so that disconnected connections do not * appear connected. + * * @alias Blockly.Events.utils.BumpEvent */ export type BumpEvent = BlockCreate|BlockMove|CommentCreate|CommentMove; @@ -227,6 +257,7 @@ export type BumpEvent = BlockCreate|BlockMove|CommentCreate|CommentMove; * * Not to be confused with bumping so that disconnected connections do not * appear connected. + * * @alias Blockly.Events.utils.BUMP_EVENTS */ export const BUMP_EVENTS: string[] = @@ -237,6 +268,7 @@ const FIRE_QUEUE: Abstract[] = []; /** * Create a custom event and fire it. + * * @param event Custom data for event. * @alias Blockly.Events.utils.fire */ @@ -246,6 +278,8 @@ export function fire(event: Abstract) { /** * Private version of fireInternal for stubbing in tests. + * + * @param event */ function fireInternal(event: Abstract) { if (!isEnabled()) { @@ -276,9 +310,10 @@ function fireNow() { /** * Filter the queued events and merge duplicates. + * * @param queueIn Array of events. * @param forward True if forward (redo), false if backward (undo). - * @return Array of filtered events. + * @returns Array of filtered events. * @alias Blockly.Events.utils.filter */ export function filter(queueIn: Abstract[], forward: boolean): Abstract[] { @@ -362,6 +397,7 @@ export function filter(queueIn: Abstract[], forward: boolean): Abstract[] { /** * Modify pending undo events so that when they are fired they don't land * in the undo stack. Called by Workspace.clearUndo. + * * @alias Blockly.Events.utils.clearPendingUndo */ export function clearPendingUndo() { @@ -372,6 +408,7 @@ export function clearPendingUndo() { /** * Stop sending events. Every call to this function MUST also call enable. + * * @alias Blockly.Events.utils.disable */ export function disable() { @@ -381,6 +418,7 @@ export function disable() { /** * Start sending events. Unless events were already disabled when the * corresponding call to disable was made. + * * @alias Blockly.Events.utils.enable */ export function enable() { @@ -389,7 +427,8 @@ export function enable() { /** * Returns whether events may be fired or not. - * @return True if enabled. + * + * @returns True if enabled. * @alias Blockly.Events.utils.isEnabled */ export function isEnabled(): boolean { @@ -398,7 +437,8 @@ export function isEnabled(): boolean { /** * Current group. - * @return ID string. + * + * @returns ID string. * @alias Blockly.Events.utils.getGroup */ export function getGroup(): string { @@ -407,6 +447,7 @@ export function getGroup(): string { /** * Start or stop a group. + * * @param state True to start new group, false to end group. * String to set group explicitly. * @alias Blockly.Events.utils.setGroup @@ -417,6 +458,8 @@ export function setGroup(state: boolean|string) { /** * Private version of setGroup for stubbing in tests. + * + * @param state */ function setGroupInternal(state: boolean|string) { if (typeof state === 'boolean') { @@ -428,8 +471,9 @@ function setGroupInternal(state: boolean|string) { /** * Compute a list of the IDs of the specified block and all its descendants. + * * @param block The root block. - * @return List of block IDs. + * @returns List of block IDs. * @alias Blockly.Events.utils.getDescendantIds * @internal */ @@ -444,9 +488,10 @@ export function getDescendantIds(block: Block): string[] { /** * Decode the JSON into an event. + * * @param json JSON representation. * @param workspace Target workspace for event. - * @return The event represented by the JSON. + * @returns The event represented by the JSON. * @throws {Error} if an event type is not found in the registry. * @alias Blockly.Events.utils.fromJson */ @@ -464,8 +509,9 @@ export function fromJson( /** * Gets the class for a specific event type from the registry. + * * @param eventType The type of the event to get. - * @return The event class with the given type or null if none exists. + * @returns The event class with the given type or null if none exists. * @alias Blockly.Events.utils.get */ export function get(eventType: string): @@ -478,6 +524,7 @@ export function get(eventType: string): * Use this on applications where all blocks should be connected to a top block. * Recommend setting the 'disable' option to 'false' in the config so that * users don't try to re-enable disabled orphan blocks. + * * @param event Custom data for event. * @alias Blockly.Events.utils.disableOrphans */ diff --git a/core/extensions.ts b/core/extensions.ts index e1f38b6c8..af2275f8c 100644 --- a/core/extensions.ts +++ b/core/extensions.ts @@ -9,6 +9,7 @@ * adding dynamic behavior such as onchange handlers and mutators. These * are applied using Block.applyExtension(), or the JSON "extensions" * array attribute. + * * @namespace Blockly.Extensions */ import * as goog from '../closure/goog/goog.js'; @@ -33,6 +34,7 @@ export const TEST_ONLY = {allExtensions}; * initialize blocks, usually adding dynamic behavior such as onchange * handlers and mutators. These are applied using Block.applyExtension(), or * the JSON "extensions" array attribute. + * * @param name The name of this extension. * @param initFn The function to initialize an extended block. * @throws {Error} if the extension name is empty, the extension is already @@ -54,6 +56,7 @@ export function register(name: string, initFn: Function) { /** * Registers a new extension function that adds all key/value of mixinObj. + * * @param name The name of this extension. * @param mixinObj The values to mix in. * @throws {Error} if the extension name is empty or the extension is already @@ -74,6 +77,7 @@ export function registerMixin(name: string, mixinObj: AnyDuringMigration) { * At register time this performs some basic sanity checks on the mutator. * The wrapper may also add a mutator dialog to the block, if both compose and * decompose are defined on the mixin. + * * @param name The name of this mutator extension. * @param mixinObj The values to mix in. * @param opt_helperFn An optional function to apply after mixing in the object. @@ -110,6 +114,7 @@ export function registerMutator( /** * Unregisters the extension registered with the given name. + * * @param name The name of the extension to unregister. * @alias Blockly.Extensions.unregister */ @@ -124,8 +129,9 @@ export function unregister(name: string) { /** * Returns whether an extension is registered with the given name. + * * @param name The name of the extension to check for. - * @return True if the extension is registered. False if it is not registered. + * @returns True if the extension is registered. False if it is not registered. * @alias Blockly.Extensions.isRegistered */ export function isRegistered(name: string): boolean { @@ -135,6 +141,7 @@ export function isRegistered(name: string): boolean { /** * Applies an extension method to a block. This should only be called during * block construction. + * * @param name The name of the extension. * @param block The block to apply the named extension to. * @param isMutator True if this extension defines a mutator. @@ -174,6 +181,7 @@ export function apply(name: string, block: Block, isMutator: boolean) { * Check that the given block does not have any of the four mutator properties * defined on it. This function should be called before applying a mutator * extension to a block, to make sure we are not overwriting properties. + * * @param mutationName The name of the mutation to reference in error messages. * @param block The block to check. * @throws {Error} if any of the properties already exist on the block. @@ -191,9 +199,10 @@ function checkNoMutatorProperties(mutationName: string, block: Block) { /** * Checks if the given object has both the 'mutationToDom' and 'domToMutation' * functions. + * * @param object The object to check. * @param errorPrefix The string to prepend to any error message. - * @return True if the object has both functions. False if it has neither + * @returns True if the object has both functions. False if it has neither * function. * @throws {Error} if the object has only one of the functions, or either is not * actually a function. @@ -207,9 +216,10 @@ function checkXmlHooks( /** * Checks if the given object has both the 'saveExtraState' and 'loadExtraState' * functions. + * * @param object The object to check. * @param errorPrefix The string to prepend to any error message. - * @return True if the object has both functions. False if it has neither + * @returns True if the object has both functions. False if it has neither * function. * @throws {Error} if the object has only one of the functions, or either is not * actually a function. @@ -223,9 +233,10 @@ function checkJsonHooks( /** * Checks if the given object has both the 'compose' and 'decompose' functions. + * * @param object The object to check. * @param errorPrefix The string to prepend to any error message. - * @return True if the object has both functions. False if it has neither + * @returns True if the object has both functions. False if it has neither * function. * @throws {Error} if the object has only one of the functions, or either is not * actually a function. @@ -239,10 +250,11 @@ function checkMutatorDialog( /** * Checks that both or neither of the given functions exist and that they are * indeed functions. + * * @param func1 The first function in the pair. * @param func2 The second function in the pair. * @param errorPrefix The string to prepend to any error message. - * @return True if the object has both functions. False if it has neither + * @returns True if the object has both functions. False if it has neither * function. * @throws {Error} If the object has only one of the functions, or either is not * actually a function. @@ -263,6 +275,7 @@ function checkHasFunctionPair( /** * Checks that the given object required mutator properties. + * * @param errorPrefix The string to prepend to any error message. * @param object The object to inspect. */ @@ -282,8 +295,9 @@ function checkHasMutatorProperties( /** * Get a list of values of mutator properties on the given block. + * * @param block The block to inspect. - * @return A list with all of the defined properties, which should be functions, + * @returns A list with all of the defined properties, which should be functions, * but may be anything other than undefined. */ function getMutatorProperties(block: Block): AnyDuringMigration[] { @@ -315,9 +329,10 @@ function getMutatorProperties(block: Block): AnyDuringMigration[] { * Check that the current mutator properties match a list of old mutator * properties. This should be called after applying a non-mutator extension, * to verify that the extension didn't change properties it shouldn't. + * * @param oldProperties The old values to compare to. * @param block The block to inspect for new values. - * @return True if the property lists match. + * @returns True if the property lists match. */ function mutatorPropertiesMatch( oldProperties: AnyDuringMigration[], block: Block): boolean { @@ -335,6 +350,7 @@ function mutatorPropertiesMatch( /** * Calls a function after the page has loaded, possibly immediately. + * * @param fn Function to run. * @throws Error Will throw if no global document can be found (e.g., Node.js). * @internal @@ -369,10 +385,11 @@ export function runAfterPageLoad(fn: () => AnyDuringMigration) { * loading the first block of any given type, the extension will validate every * dropdown option has a matching tooltip in the lookupTable. Errors are * reported as warnings in the console, and are never fatal. + * * @param dropdownName The name of the field whose value is the key to the * lookup table. * @param lookupTable The table of field values to tooltip text. - * @return The extension function. + * @returns The extension function. * @alias Blockly.Extensions.buildTooltipForDropdown */ export function buildTooltipForDropdown( @@ -393,7 +410,11 @@ export function buildTooltipForDropdown( }); } - /** The actual extension. */ + /** + * The actual extension. + * + * @param this + */ function extensionFn(this: Block) { if (this.type && blockTypesChecked.indexOf(this.type) === -1) { checkDropdownOptionsInTable(this, dropdownName, lookupTable); @@ -425,6 +446,7 @@ export function buildTooltipForDropdown( /** * Checks all options keys are present in the provided string lookup table. * Emits console warnings when they are not. + * * @param block The block containing the dropdown * @param dropdownName The name of the dropdown * @param lookupTable The string lookup table @@ -450,10 +472,11 @@ function checkDropdownOptionsInTable( * Builds an extension function that will install a dynamic tooltip. The * tooltip message should include the string '%1' and that string will be * replaced with the text of the named field. + * * @param msgTemplate The template form to of the message text, with %1 * placeholder. * @param fieldName The field with the replacement text. - * @return The extension function. + * @returns The extension function. * @alias Blockly.Extensions.buildTooltipWithFieldText */ export function buildTooltipWithFieldText( @@ -469,7 +492,11 @@ export function buildTooltipWithFieldText( }); } - /** The actual extension. */ + /** + * The actual extension. + * + * @param this + */ function extensionFn(this: Block) { this.setTooltip(function(this: Block) { const field = this.getField(fieldName); @@ -485,6 +512,8 @@ export function buildTooltipWithFieldText( * uses the tooltip text at the time this extension is initialized. This takes * advantage of the fact that all other values from JSON are initialized before * extensions. + * + * @param this */ function extensionParentTooltip(this: Block) { const tooltipWhenNotConnected = this.tooltip; diff --git a/core/field_angle.ts b/core/field_angle.ts index a92cfedf5..26a6a7eb4 100644 --- a/core/field_angle.ts +++ b/core/field_angle.ts @@ -6,6 +6,7 @@ /** * Angle input field. + * * @class */ import * as goog from '../closure/goog/goog.js'; @@ -29,6 +30,7 @@ import * as WidgetDiv from './widgetdiv.js'; /** * Class for an editable angle field. + * * @alias Blockly.FieldAngle */ export class FieldAngle extends FieldTextInput { @@ -123,24 +125,28 @@ export class FieldAngle extends FieldTextInput { /** * Should the angle increase as the angle picker is moved clockwise (true) * or counterclockwise (false) + * * @see FieldAngle.CLOCKWISE */ this.clockwise_ = FieldAngle.CLOCKWISE; /** * The offset of zero degrees (and all other angles). + * * @see FieldAngle.OFFSET */ this.offset_ = FieldAngle.OFFSET; /** * The maximum angle to allow before wrapping. + * * @see FieldAngle.WRAP */ this.wrap_ = FieldAngle.WRAP; /** * The amount to round angles to when using a mouse or keyboard nav input. + * * @see FieldAngle.ROUND */ this.round_ = FieldAngle.ROUND; @@ -159,6 +165,7 @@ export class FieldAngle extends FieldTextInput { /** * Configure the field based on the given map of options. + * * @param config A map of options to configure the field based on. */ protected override configure_(config: FieldAngleConfig) { @@ -186,6 +193,7 @@ export class FieldAngle extends FieldTextInput { /** * Create the block UI for this field. + * * @internal */ override initView() { @@ -205,6 +213,7 @@ export class FieldAngle extends FieldTextInput { /** * Create and show the angle field's editor. + * * @param opt_e Optional mouse event that triggered the field to open, or * undefined if triggered programmatically. */ @@ -317,6 +326,7 @@ export class FieldAngle extends FieldTextInput { /** * Set the angle to match the mouse's position. + * * @param e Mouse move event. */ protected onMouseMove_(e: Event) { @@ -355,6 +365,7 @@ export class FieldAngle extends FieldTextInput { * Handles and displays values that are input via mouse or arrow key input. * These values need to be rounded and wrapped before being displayed so * that the text input's value is appropriate. + * * @param angle New angle. */ private displayMouseOrKeyboardValue_(angle: number) { @@ -410,6 +421,7 @@ export class FieldAngle extends FieldTextInput { /** * Handle key down to the editor. + * * @param e Keyboard event. */ protected override onHtmlInputKeyDown_(e: Event) { @@ -447,8 +459,9 @@ export class FieldAngle extends FieldTextInput { /** * Ensure that the input value is a valid angle. + * * @param opt_newValue The input value. - * @return A valid angle, or null if invalid. + * @returns A valid angle, or null if invalid. */ protected override doClassValidation_(opt_newValue?: AnyDuringMigration): number|null { @@ -461,8 +474,9 @@ export class FieldAngle extends FieldTextInput { /** * Wraps the value so that it is in the range (-360 + wrap, wrap). + * * @param value The value to wrap. - * @return The wrapped value. + * @returns The wrapped value. */ private wrapValue_(value: number): number { value %= 360; @@ -477,8 +491,9 @@ export class FieldAngle extends FieldTextInput { /** * Construct a FieldAngle from a JSON arg object. + * * @param options A JSON object with options (angle). - * @return The new field instance. + * @returns The new field instance. * @nocollapse * @internal */ diff --git a/core/field_colour.ts b/core/field_colour.ts index e5b03f550..b251917a6 100644 --- a/core/field_colour.ts +++ b/core/field_colour.ts @@ -6,6 +6,7 @@ /** * Colour input field. + * * @class */ import * as goog from '../closure/goog/goog.js'; @@ -31,6 +32,7 @@ import {Size} from './utils/size.js'; /** * Class for a colour input field. + * * @alias Blockly.FieldColour */ export class FieldColour extends Field { @@ -168,6 +170,7 @@ export class FieldColour extends Field { /** * Configure the field based on the given map of options. + * * @param config A map of options to configure the field based on. */ protected override configure_(config: FieldColourConfig) { @@ -179,6 +182,7 @@ export class FieldColour extends Field { /** * Create the block UI for this colour field. + * * @internal */ override initView() { @@ -207,8 +211,9 @@ export class FieldColour extends Field { /** * Ensure that the input value is a valid colour. + * * @param opt_newValue The input value. - * @return A valid colour, or null if invalid. + * @returns A valid colour, or null if invalid. */ protected override doClassValidation_(opt_newValue?: AnyDuringMigration): string|null { @@ -220,6 +225,7 @@ export class FieldColour extends Field { /** * Update the value of this colour field, and update the displayed colour. + * * @param newValue The value to be saved. The default validator guarantees * that this is a colour in '#rrggbb' format. */ @@ -238,7 +244,8 @@ export class FieldColour extends Field { /** * Get the text for this field. Used when the block is collapsed. - * @return Text representing the value of this field. + * + * @returns Text representing the value of this field. */ override getText(): string { let colour = this.value_ as string; @@ -251,11 +258,12 @@ export class FieldColour extends Field { /** * Set a custom colour grid for this field. + * * @param colours Array of colours for this block, or null to use default * (FieldColour.COLOURS). * @param opt_titles Optional array of colour tooltips, or null to use default * (FieldColour.TITLES). - * @return Returns itself (for method chaining). + * @returns Returns itself (for method chaining). */ setColours(colours: string[], opt_titles?: string[]): FieldColour { this.colours_ = colours; @@ -267,9 +275,10 @@ export class FieldColour extends Field { /** * Set a custom grid size for this field. + * * @param columns Number of columns for this block, or 0 to use default * (FieldColour.COLUMNS). - * @return Returns itself (for method chaining). + * @returns Returns itself (for method chaining). */ setColumns(columns: number): FieldColour { this.columns_ = columns; @@ -293,6 +302,7 @@ export class FieldColour extends Field { /** * Handle a click on a colour cell. + * * @param e Mouse event. */ private onClick_(e: MouseEvent) { @@ -307,6 +317,7 @@ export class FieldColour extends Field { /** * Handle a key down event. Navigate around the grid with the * arrow keys. Enter selects the highlighted colour. + * * @param e Keyboard event. */ private onKeyDown_(e: KeyboardEvent) { @@ -342,6 +353,7 @@ export class FieldColour extends Field { /** * Move the currently highlighted position by dx and dy. + * * @param dx Change of x * @param dy Change of y */ @@ -399,6 +411,7 @@ export class FieldColour extends Field { /** * Handle a mouse move event. Highlight the hovered colour. + * * @param e Mouse event. */ private onMouseMove_(e: MouseEvent) { @@ -432,7 +445,8 @@ export class FieldColour extends Field { /** * Returns the currently highlighted item (if any). - * @return Highlighted item (null if none). + * + * @returns Highlighted item (null if none). */ private getHighlighted_(): HTMLElement|null { if (!this.highlightedIndex_) { @@ -452,6 +466,7 @@ export class FieldColour extends Field { /** * Update the currently highlighted cell. + * * @param cell the new cell to highlight * @param index the index of the new cell */ @@ -559,8 +574,9 @@ export class FieldColour extends Field { /** * Construct a FieldColour from a JSON arg object. + * * @param options A JSON object with options (colour). - * @return The new field instance. + * @returns The new field instance. * @nocollapse * @internal */ diff --git a/core/field_image.ts b/core/field_image.ts index fd411d642..9d0d527e6 100644 --- a/core/field_image.ts +++ b/core/field_image.ts @@ -6,6 +6,7 @@ /** * Image field. Used for pictures, icons, etc. + * * @class */ import * as goog from '../closure/goog/goog.js'; @@ -22,6 +23,7 @@ import {Svg} from './utils/svg.js'; /** * Class for an image on a block. + * * @alias Blockly.FieldImage */ export class FieldImage extends Field { @@ -123,6 +125,7 @@ export class FieldImage extends Field { /** * Configure the field based on the given map of options. + * * @param config A map of options to configure the field based on. */ protected override configure_(config: FieldImageConfig) { @@ -135,6 +138,7 @@ export class FieldImage extends Field { /** * Create the block UI for this image. + * * @internal */ override initView() { @@ -158,8 +162,9 @@ export class FieldImage extends Field { /** * Ensure that the input value (the source URL) is a string. + * * @param opt_newValue The input value. - * @return A string, or null if invalid. + * @returns A string, or null if invalid. */ protected override doClassValidation_(opt_newValue?: AnyDuringMigration): string|null { @@ -171,6 +176,7 @@ export class FieldImage extends Field { /** * Update the value of this image field, and update the displayed image. + * * @param newValue The value to be saved. The default validator guarantees * that this is a string. */ @@ -184,7 +190,8 @@ export class FieldImage extends Field { /** * Get whether to flip this image in RTL - * @return True if we should flip in RTL. + * + * @returns True if we should flip in RTL. */ override getFlipRtl(): boolean { return this.flipRtl_; @@ -192,6 +199,7 @@ export class FieldImage extends Field { /** * Set the alt text of this image. + * * @param alt New alt text. */ setAlt(alt: string|null) { @@ -216,6 +224,7 @@ export class FieldImage extends Field { /** * Set the function that is called when this image is clicked. + * * @param func The function that is called when the image is clicked, or null * to remove. */ @@ -227,7 +236,8 @@ export class FieldImage extends Field { * Use the `getText_` developer hook to override the field's text * representation. * Return the image alt text instead. - * @return The image alt text. + * + * @returns The image alt text. */ protected override getText_(): string|null { return this.altText_; @@ -236,9 +246,10 @@ export class FieldImage extends Field { /** * Construct a FieldImage from a JSON arg object, * dereferencing any string table references. + * * @param options A JSON object with options (src, width, height, alt, and * flipRtl). - * @return The new field instance. + * @returns The new field instance. * @nocollapse * @internal */ diff --git a/core/field_label.ts b/core/field_label.ts index 4e1a97a10..48cf38f8e 100644 --- a/core/field_label.ts +++ b/core/field_label.ts @@ -7,6 +7,7 @@ /** * Non-editable, non-serializable text field. Used for titles, * labels, etc. + * * @class */ import * as goog from '../closure/goog/goog.js'; @@ -21,6 +22,7 @@ import type {Sentinel} from './utils/sentinel.js'; /** * Class for a non-editable, non-serializable text field. + * * @alias Blockly.FieldLabel */ export class FieldLabel extends Field { @@ -68,6 +70,7 @@ export class FieldLabel extends Field { /** * Create block UI for this label. + * * @internal */ override initView() { @@ -79,8 +82,9 @@ export class FieldLabel extends Field { /** * Ensure that the input value casts to a valid string. + * * @param opt_newValue The input value. - * @return A valid string, or null if invalid. + * @returns A valid string, or null if invalid. */ protected override doClassValidation_(opt_newValue?: AnyDuringMigration): string|null { @@ -92,6 +96,7 @@ export class FieldLabel extends Field { /** * Set the CSS class applied to the field's textElement_. + * * @param cssClass The new CSS class name, or null to remove. */ setClass(cssClass: string|null) { @@ -111,8 +116,9 @@ export class FieldLabel extends Field { /** * Construct a FieldLabel from a JSON arg object, * dereferencing any string table references. + * * @param options A JSON object with options (text, and class). - * @return The new field instance. + * @returns The new field instance. * @nocollapse * @internal */ diff --git a/core/field_multilineinput.ts b/core/field_multilineinput.ts index fd663955f..40fb603db 100644 --- a/core/field_multilineinput.ts +++ b/core/field_multilineinput.ts @@ -6,6 +6,7 @@ /** * Text Area field. + * * @class */ import * as goog from '../closure/goog/goog.js'; @@ -27,6 +28,7 @@ import * as WidgetDiv from './widgetdiv.js'; /** * Class for an editable text area field. + * * @alias Blockly.FieldMultilineInput */ export class FieldMultilineInput extends FieldTextInput { @@ -86,9 +88,10 @@ export class FieldMultilineInput extends FieldTextInput { /** * Serializes this field's value to XML. Should only be called by Blockly.Xml. + * * @param fieldElement The element to populate with info about the field's * state. - * @return The element containing info about the field's state. + * @returns The element containing info about the field's state. * @internal */ override toXml(fieldElement: Element): Element { @@ -104,6 +107,7 @@ export class FieldMultilineInput extends FieldTextInput { /** * Sets the field's value based on the given XML element. Should only be * called by Blockly.Xml. + * * @param fieldElement The element containing info about the field's state. * @internal */ @@ -113,7 +117,8 @@ export class FieldMultilineInput extends FieldTextInput { /** * Saves this field's value. - * @return The state of this field. + * + * @returns The state of this field. * @internal */ override saveState(): AnyDuringMigration { @@ -126,6 +131,7 @@ export class FieldMultilineInput extends FieldTextInput { /** * Sets the field's value based on the given state. + * * @param state The state of the variable to assign to this variable field. * @internal */ @@ -138,6 +144,7 @@ export class FieldMultilineInput extends FieldTextInput { /** * Create the block UI for this field. + * * @internal */ override initView() { @@ -152,7 +159,8 @@ export class FieldMultilineInput extends FieldTextInput { /** * Get the text from this field as displayed on screen. May differ from * getText due to ellipsis, and other formatting. - * @return Currently displayed text. + * + * @returns Currently displayed text. */ protected override getDisplayText_(): string { let textLines = this.getText(); @@ -193,6 +201,7 @@ export class FieldMultilineInput extends FieldTextInput { * field, and updates the text of the field if it is not currently being * edited (i.e. handled by the htmlInput_). Is being redefined here to update * overflow state of the field. + * * @param newValue The value to be saved. The default validator guarantees * that this is a string. */ @@ -323,6 +332,7 @@ export class FieldMultilineInput extends FieldTextInput { * Show the inline free-text editor on top of the text. * Overrides the default behaviour to force rerender in order to * correct block size, based on editor text. + * * @param _opt_e Optional mouse event that triggered the field to open, or * undefined if triggered programmatically. * @param opt_quietInput True if editor should be created without focus. @@ -335,7 +345,8 @@ export class FieldMultilineInput extends FieldTextInput { /** * Create the text input editor widget. - * @return The newly created text input editor. + * + * @returns The newly created text input editor. */ protected override widgetCreate_(): HTMLTextAreaElement { const div = WidgetDiv.getDiv(); @@ -380,6 +391,7 @@ export class FieldMultilineInput extends FieldTextInput { /** * Sets the maxLines config for this field. + * * @param maxLines Defines the maximum number of lines allowed, before * scrolling functionality is enabled. */ @@ -393,7 +405,8 @@ export class FieldMultilineInput extends FieldTextInput { /** * Returns the maxLines config of this field. - * @return The maxLines config value. + * + * @returns The maxLines config value. */ getMaxLines(): number { return this.maxLines_; @@ -402,6 +415,7 @@ export class FieldMultilineInput extends FieldTextInput { /** * Handle key down to the editor. Override the text input definition of this * so as to not close the editor when enter is typed in. + * * @param e Keyboard event. */ protected override onHtmlInputKeyDown_(e: Event) { @@ -415,8 +429,9 @@ export class FieldMultilineInput extends FieldTextInput { /** * Construct a FieldMultilineInput from a JSON arg object, * dereferencing any string table references. + * * @param options A JSON object with options (text, and spellcheck). - * @return The new field instance. + * @returns The new field instance. * @nocollapse * @internal */ diff --git a/core/field_number.ts b/core/field_number.ts index 4a80d09c5..91a780299 100644 --- a/core/field_number.ts +++ b/core/field_number.ts @@ -6,6 +6,7 @@ /** * Number input field + * * @class */ import * as goog from '../closure/goog/goog.js'; @@ -20,6 +21,7 @@ import type {Sentinel} from './utils/sentinel.js'; /** * Class for an editable number field. + * * @alias Blockly.FieldNumber */ export class FieldNumber extends FieldTextInput { @@ -86,6 +88,7 @@ export class FieldNumber extends FieldTextInput { /** * Configure the field based on the given map of options. + * * @param config A map of options to configure the field based on. */ protected override configure_(config: FieldNumberConfig) { @@ -103,6 +106,7 @@ export class FieldNumber extends FieldTextInput { * precision. The least significant digit place is inferred from the * precision. Integers values can be enforces by choosing an integer * precision. + * * @param min Minimum value. * @param max Maximum value. * @param precision Precision for value. @@ -119,6 +123,7 @@ export class FieldNumber extends FieldTextInput { /** * Sets the minimum value this field can contain. Updates the value to * reflect. + * * @param min Minimum value. */ setMin(min: number|string|undefined|null) { @@ -129,6 +134,7 @@ export class FieldNumber extends FieldTextInput { /** * Sets the minimum value this field can contain. Called internally to avoid * value updates. + * * @param min Minimum value. */ private setMinInternal_(min: number|string|undefined|null) { @@ -145,7 +151,8 @@ export class FieldNumber extends FieldTextInput { /** * Returns the current minimum value this field can contain. Default is * -Infinity. - * @return The current minimum value this field can contain. + * + * @returns The current minimum value this field can contain. */ getMin(): number { return this.min_; @@ -154,6 +161,7 @@ export class FieldNumber extends FieldTextInput { /** * Sets the maximum value this field can contain. Updates the value to * reflect. + * * @param max Maximum value. */ setMax(max: number|string|undefined|null) { @@ -164,6 +172,7 @@ export class FieldNumber extends FieldTextInput { /** * Sets the maximum value this field can contain. Called internally to avoid * value updates. + * * @param max Maximum value. */ private setMaxInternal_(max: number|string|undefined|null) { @@ -180,7 +189,8 @@ export class FieldNumber extends FieldTextInput { /** * Returns the current maximum value this field can contain. Default is * Infinity. - * @return The current maximum value this field can contain. + * + * @returns The current maximum value this field can contain. */ getMax(): number { return this.max_; @@ -189,6 +199,7 @@ export class FieldNumber extends FieldTextInput { /** * Sets the precision of this field's value, i.e. the number to which the * value is rounded. Updates the field to reflect. + * * @param precision The number to which the field's value is rounded. */ setPrecision(precision: number|string|undefined|null) { @@ -199,6 +210,7 @@ export class FieldNumber extends FieldTextInput { /** * Sets the precision of this field's value. Called internally to avoid * value updates. + * * @param precision The number to which the field's value is rounded. */ private setPrecisionInternal_(precision: number|string|undefined|null) { @@ -224,7 +236,8 @@ export class FieldNumber extends FieldTextInput { * Returns the current precision of this field. The precision being the * number to which the field's value is rounded. A precision of 0 means that * the value is not rounded. - * @return The number to which this field's value is rounded. + * + * @returns The number to which this field's value is rounded. */ getPrecision(): number { return this.precision_; @@ -233,8 +246,9 @@ export class FieldNumber extends FieldTextInput { /** * Ensure that the input value is a valid number (must fulfill the * constraints placed on the field). + * * @param opt_newValue The input value. - * @return A valid number, or null if invalid. + * @returns A valid number, or null if invalid. */ protected override doClassValidation_(opt_newValue?: AnyDuringMigration): number|null { @@ -272,7 +286,8 @@ export class FieldNumber extends FieldTextInput { /** * Create the number input editor widget. - * @return The newly created number input editor. + * + * @returns The newly created number input editor. */ protected override widgetCreate_(): HTMLElement { const htmlInput = super.widgetCreate_(); @@ -289,8 +304,9 @@ export class FieldNumber extends FieldTextInput { /** * Construct a FieldNumber from a JSON arg object. + * * @param options A JSON object with options (value, min, max, and precision). - * @return The new field instance. + * @returns The new field instance. * @nocollapse * @internal */ diff --git a/core/field_textinput.ts b/core/field_textinput.ts index 89530ab1c..2872526cb 100644 --- a/core/field_textinput.ts +++ b/core/field_textinput.ts @@ -6,6 +6,7 @@ /** * Text input field. + * * @class */ import * as goog from '../closure/goog/goog.js'; @@ -35,6 +36,7 @@ import type {WorkspaceSvg} from './workspace_svg.js'; /** * Class for an editable text field. + * * @alias Blockly.FieldTextInput */ export class FieldTextInput extends Field { @@ -157,8 +159,9 @@ export class FieldTextInput extends Field { /** * Ensure that the input value casts to a valid string. + * * @param opt_newValue The input value. - * @return A valid string, or null if invalid. + * @returns A valid string, or null if invalid. */ protected override doClassValidation_(opt_newValue?: AnyDuringMigration): AnyDuringMigration { @@ -172,6 +175,7 @@ export class FieldTextInput extends Field { * Called by setValue if the text input is not valid. If the field is * currently being edited it reverts value of the field to the previous * value while allowing the display text to be handled by the htmlInput_. + * * @param _invalidValue The input value that was determined to be invalid. * This is not used by the text input because its display value is stored * on the htmlInput_. @@ -194,6 +198,7 @@ export class FieldTextInput extends Field { * Called by setValue if the text input is valid. Updates the value of the * field, and updates the text of the field if it is not currently being * edited (i.e. handled by the htmlInput_). + * * @param newValue The value to be saved. The default validator guarantees * that this is a string. */ @@ -208,6 +213,7 @@ export class FieldTextInput extends Field { /** * Updates text field to match the colour/style of the block. + * * @internal */ override applyColour() { @@ -246,6 +252,7 @@ export class FieldTextInput extends Field { /** * Set whether this field is spellchecked by the browser. + * * @param check True if checked. */ setSpellcheck(check: boolean) { @@ -263,6 +270,7 @@ export class FieldTextInput extends Field { /** * Show the inline free-text editor on top of the text. + * * @param _opt_e Optional mouse event that triggered the field to open, or * undefined if triggered programmatically. * @param opt_quietInput True if editor should be created without focus. @@ -295,6 +303,7 @@ export class FieldTextInput extends Field { /** * Create and show a text input editor that sits directly over the text input. + * * @param quietInput True if editor should be created without focus. */ private showInlineEditor_(quietInput: boolean) { @@ -312,7 +321,8 @@ export class FieldTextInput extends Field { /** * Create the text input editor widget. - * @return The newly created text input editor. + * + * @returns The newly created text input editor. */ protected widgetCreate_(): HTMLElement { eventUtils.setGroup(true); @@ -392,6 +402,7 @@ export class FieldTextInput extends Field { /** * A callback triggered when the user is done editing the field via the UI. + * * @param _value The new value of the field. */ onFinishEditing_(_value: AnyDuringMigration) {} @@ -400,6 +411,7 @@ export class FieldTextInput extends Field { /** * Bind handlers for user input on the text input field's editor. + * * @param htmlInput The htmlInput to which event handlers will be bound. */ protected bindInputEvents_(htmlInput: HTMLElement) { @@ -425,6 +437,7 @@ export class FieldTextInput extends Field { /** * Handle key down to the editor. + * * @param e Keyboard event. */ protected onHtmlInputKeyDown_(e: Event) { @@ -456,6 +469,7 @@ export class FieldTextInput extends Field { /** * Handle a change to the editor. + * * @param _e Keyboard event. */ private onHtmlInputChange_(_e: Event) { @@ -474,6 +488,7 @@ export class FieldTextInput extends Field { * Set the HTML input value and the field's internal value. The difference * between this and ``setValue`` is that this also updates the HTML input * value whilst editing. + * * @param newValue New value. */ protected setEditorValue_(newValue: AnyDuringMigration) { @@ -506,7 +521,8 @@ export class FieldTextInput extends Field { /** * Returns whether or not the field is tab navigable. - * @return True if the field is tab navigable. + * + * @returns True if the field is tab navigable. */ override isTabNavigable(): boolean { return true; @@ -517,7 +533,8 @@ export class FieldTextInput extends Field { * representation. When we're currently editing, return the current HTML value * instead. Otherwise, return null which tells the field to use the default * behaviour (which is a string cast of the field's value). - * @return The HTML value if we're editing, otherwise null. + * + * @returns The HTML value if we're editing, otherwise null. */ protected override getText_(): string|null { if (this.isBeingEdited_ && this.htmlInput_) { @@ -532,8 +549,9 @@ export class FieldTextInput extends Field { * Override this method if the field's HTML input representation is different * than the field's value. This should be coupled with an override of * `getValueFromEditorText_`. + * * @param value The value stored in this field. - * @return The text to show on the HTML input. + * @returns The text to show on the HTML input. */ protected getEditorText_(value: AnyDuringMigration): string { return String(value); @@ -545,8 +563,9 @@ export class FieldTextInput extends Field { * Override this method if the field's HTML input representation is different * than the field's value. This should be coupled with an override of * `getEditorText_`. + * * @param text Text received from the HTML input. - * @return The value to store. + * @returns The value to store. */ protected getValueFromEditorText_(text: string): AnyDuringMigration { return text; @@ -555,8 +574,9 @@ export class FieldTextInput extends Field { /** * Construct a FieldTextInput from a JSON arg object, * dereferencing any string table references. + * * @param options A JSON object with options (text, and spellcheck). - * @return The new field instance. + * @returns The new field instance. * @nocollapse * @internal */ diff --git a/core/field_variable.ts b/core/field_variable.ts index aee652561..3167e6197 100644 --- a/core/field_variable.ts +++ b/core/field_variable.ts @@ -6,6 +6,7 @@ /** * Variable input field. + * * @class */ import * as goog from '../closure/goog/goog.js'; @@ -32,6 +33,7 @@ import * as Xml from './xml.js'; /** * Class for a variable's dropdown field. + * * @alias Blockly.FieldVariable */ export class FieldVariable extends FieldDropdown { @@ -117,6 +119,7 @@ export class FieldVariable extends FieldDropdown { /** * Configure the field based on the given map of options. + * * @param config A map of options to configure the field based on. */ protected override configure_(config: FieldVariableConfig) { @@ -128,6 +131,7 @@ export class FieldVariable extends FieldDropdown { * Initialize the model for this field if it has not already been initialized. * If the value has not been set to a variable by the first render, we make up * a variable rather than let the value be invalid. + * * @internal */ override initModel() { @@ -149,6 +153,7 @@ export class FieldVariable extends FieldDropdown { /** * Initialize this field based on the given XML. + * * @param fieldElement The element containing information about the variable * field's state. */ @@ -180,9 +185,10 @@ export class FieldVariable extends FieldDropdown { /** * Serialize this field to XML. + * * @param fieldElement The element to populate with info about the field's * state. - * @return The element containing info about the field's state. + * @returns The element containing info about the field's state. */ override toXml(fieldElement: Element): Element { // Make sure the variable is initialized. @@ -198,10 +204,11 @@ export class FieldVariable extends FieldDropdown { /** * Saves this field's value. + * * @param doFullSerialization If true, the variable field will serialize the * full state of the field being referenced (ie ID, name, and type) rather * than just a reference to it (ie ID). - * @return The state of the variable field. + * @returns The state of the variable field. * @internal */ override saveState(doFullSerialization?: boolean): AnyDuringMigration { @@ -221,6 +228,7 @@ export class FieldVariable extends FieldDropdown { /** * Sets the field's value based on the given state. + * * @param state The state of the variable to assign to this variable field. * @internal */ @@ -237,6 +245,7 @@ export class FieldVariable extends FieldDropdown { /** * Attach this field to a block. + * * @param block The block containing this field. */ override setSourceBlock(block: Block) { @@ -248,7 +257,8 @@ export class FieldVariable extends FieldDropdown { /** * Get the variable's ID. - * @return Current variable's ID. + * + * @returns Current variable's ID. */ override getValue(): string|null { return this.variable_ ? this.variable_.getId() : null; @@ -256,7 +266,8 @@ export class FieldVariable extends FieldDropdown { /** * Get the text from this field, which is the selected variable's name. - * @return The selected variable's name, or the empty string if no variable is + * + * @returns The selected variable's name, or the empty string if no variable is * selected. */ override getText(): string { @@ -267,7 +278,8 @@ export class FieldVariable extends FieldDropdown { * Get the variable model for the selected variable. * Not guaranteed to be in the variable map on the workspace (e.g. if accessed * after the variable has been deleted). - * @return The selected variable, or null if none was selected. + * + * @returns The selected variable, or null if none was selected. * @internal */ getVariable(): VariableModel|null { @@ -279,7 +291,8 @@ export class FieldVariable extends FieldDropdown { * Returns null if the variable is not set, because validators should not * run on the initial setValue call, because the field won't be attached to * a block and workspace at that point. - * @return Validation function, or null. + * + * @returns Validation function, or null. */ override getValidator(): Function|null { // Validators shouldn't operate on the initial setValue call. @@ -293,8 +306,9 @@ export class FieldVariable extends FieldDropdown { /** * Ensure that the ID belongs to a valid variable of an allowed type. + * * @param opt_newValue The ID of the new variable to set. - * @return The validated ID, or null if invalid. + * @returns The validated ID, or null if invalid. */ protected override doClassValidation_(opt_newValue?: AnyDuringMigration): string|null { @@ -324,6 +338,7 @@ export class FieldVariable extends FieldDropdown { * * The variable ID should be valid at this point, but if a variable field * validator returns a bad ID, this could break. + * * @param newId The value to be saved. */ protected override doValueUpdate_(newId: AnyDuringMigration) { @@ -334,8 +349,9 @@ export class FieldVariable extends FieldDropdown { /** * Check whether the given variable type is allowed on this field. + * * @param type The type to check. - * @return True if the type is in the list of allowed types. + * @returns True if the type is in the list of allowed types. */ private typeIsAllowed_(type: string): boolean { const typeList = this.getVariableTypes_(); @@ -352,7 +368,8 @@ export class FieldVariable extends FieldDropdown { /** * Return a list of variable types to include in the dropdown. - * @return Array of variable types. + * + * @returns Array of variable types. * @throws {Error} if variableTypes is an empty array. */ private getVariableTypes_(): string[] { @@ -377,6 +394,7 @@ export class FieldVariable extends FieldDropdown { /** * Parse the optional arguments representing the allowed variable types and * the default variable type. + * * @param opt_variableTypes A list of the types of variables to include in the * dropdown. If null or undefined, variables of all types will be * displayed in the dropdown. @@ -420,6 +438,7 @@ export class FieldVariable extends FieldDropdown { * Refreshes the name of the variable by grabbing the name of the model. * Used when a variable gets renamed, but the ID stays the same. Should only * be called by the block. + * * @internal */ override refreshVariableName() { @@ -430,6 +449,7 @@ export class FieldVariable extends FieldDropdown { * Handle the selection of an item in the variable dropdown menu. * Special case the 'Rename variable...' and 'Delete variable...' options. * In the rename case, prompt the user for a new name. + * * @param menu The Menu component clicked. * @param menuItem The MenuItem selected within menu. */ @@ -455,7 +475,8 @@ export class FieldVariable extends FieldDropdown { /** * Overrides referencesVariables(), indicating this field refers to a * variable. - * @return True. + * + * @returns True. * @internal */ override referencesVariables(): boolean { @@ -465,9 +486,10 @@ export class FieldVariable extends FieldDropdown { /** * Construct a FieldVariable from a JSON arg object, * dereferencing any string table references. + * * @param options A JSON object with options (variable, variableTypes, and * defaultType). - * @return The new field instance. + * @returns The new field instance. * @nocollapse * @internal */ @@ -482,7 +504,9 @@ export class FieldVariable extends FieldDropdown { /** * Return a sorted list of variable names for variable dropdown menus. * Include a special option at the end for creating a new variable name. - * @return Array of variable names/id tuples. + * + * @param this + * @returns Array of variable names/id tuples. */ static dropdownCreate(this: FieldVariable): AnyDuringMigration[][] { if (!this.variable_) { diff --git a/core/flyout_button.ts b/core/flyout_button.ts index 15ae5836c..256df77fd 100644 --- a/core/flyout_button.ts +++ b/core/flyout_button.ts @@ -6,6 +6,7 @@ /** * Class for a button in the flyout. + * * @class */ import * as goog from '../closure/goog/goog.js'; @@ -24,6 +25,7 @@ import type {WorkspaceSvg} from './workspace_svg.js'; /** * Class for a button or label in the flyout. + * * @alias Blockly.FlyoutButton */ export class FlyoutButton { @@ -84,7 +86,8 @@ export class FlyoutButton { /** * Create the button elements. - * @return The button's SVG group. + * + * @returns The button's SVG group. */ createDom(): SVGElement { let cssClass = this.isLabel_ ? 'blocklyFlyoutLabel' : 'blocklyFlyoutButton'; @@ -186,6 +189,7 @@ export class FlyoutButton { /** * Move the button to the given x, y coordinates. + * * @param x The new x coordinate. * @param y The new y coordinate. */ @@ -195,28 +199,30 @@ export class FlyoutButton { this.updateTransform_(); } - /** @return Whether or not the button is a label. */ + /** @returns Whether or not the button is a label. */ isLabel(): boolean { return this.isLabel_; } /** * Location of the button. - * @return x, y coordinates. + * + * @returns x, y coordinates. * @internal */ getPosition(): Coordinate { return this.position_; } - /** @return Text of the button. */ + /** @returns Text of the button. */ getButtonText(): string { return this.text_; } /** * Get the button's target workspace. - * @return The target workspace of the flyout where this button resides. + * + * @returns The target workspace of the flyout where this button resides. */ getTargetWorkspace(): WorkspaceSvg { return this.targetWorkspace; @@ -237,6 +243,7 @@ export class FlyoutButton { /** * Do something when the button is clicked. + * * @param e Mouse up event. */ private onMouseUp_(e: Event) { diff --git a/core/flyout_horizontal.ts b/core/flyout_horizontal.ts index 00f6e08cc..b6d4dcf6c 100644 --- a/core/flyout_horizontal.ts +++ b/core/flyout_horizontal.ts @@ -6,6 +6,7 @@ /** * Horizontal flyout tray containing blocks which may be created. + * * @class */ import * as goog from '../closure/goog/goog.js'; @@ -26,6 +27,7 @@ import * as WidgetDiv from './widgetdiv.js'; /** * Class for a flyout. + * * @alias Blockly.HorizontalFlyout */ export class HorizontalFlyout extends Flyout { @@ -43,8 +45,11 @@ export class HorizontalFlyout extends Flyout { /** * Sets the translation of the flyout to match the scrollbars. + * * @param xyRatio Contains a y property which is a float between 0 and 1 * specifying the degree of scrolling and a similar x property. + * @param xyRatio.x + * @param xyRatio.y */ protected override setMetrics_(xyRatio: {x: number, y: number}) { if (!this.isVisible()) { @@ -69,7 +74,8 @@ export class HorizontalFlyout extends Flyout { /** * Calculates the x coordinate for the flyout position. - * @return X coordinate. + * + * @returns X coordinate. */ override getX(): number { // X is always 0 since this is a horizontal flyout. @@ -78,7 +84,8 @@ export class HorizontalFlyout extends Flyout { /** * Calculates the y coordinate for the flyout position. - * @return Y coordinate. + * + * @returns Y coordinate. */ override getY(): number { if (!this.isVisible()) { @@ -146,6 +153,7 @@ export class HorizontalFlyout extends Flyout { /** * Create and set the path for the visible boundaries of the flyout. + * * @param width The width of the flyout, not including the rounded corners. * @param height The height of the flyout, not including rounded corners. */ @@ -195,6 +203,7 @@ export class HorizontalFlyout extends Flyout { /** * Scroll the flyout. + * * @param e Mouse wheel scroll event. */ protected override wheel_(e: WheelEvent) { @@ -221,6 +230,7 @@ export class HorizontalFlyout extends Flyout { /** * Lay out the blocks in the flyout. + * * @param contents The blocks and buttons to lay out. * @param gaps The visible gaps between blocks. */ @@ -277,9 +287,10 @@ export class HorizontalFlyout extends Flyout { * Determine if a drag delta is toward the workspace, based on the position * and orientation of the flyout. This is used in determineDragIntention_ to * determine if a new block should be created or if the flyout should scroll. + * * @param currentDragDeltaXY How far the pointer has moved from the position * at mouse down, in pixel units. - * @return True if the drag is toward the workspace. + * @returns True if the drag is toward the workspace. * @internal */ override isDragTowardWorkspace(currentDragDeltaXY: Coordinate): boolean { @@ -300,7 +311,8 @@ export class HorizontalFlyout extends Flyout { /** * Returns the bounding rectangle of the drag target area in pixel units * relative to viewport. - * @return The component's bounding box. Null if drag target area should be + * + * @returns The component's bounding box. Null if drag target area should be * ignored. */ override getClientRect(): Rect|null { diff --git a/core/flyout_metrics_manager.ts b/core/flyout_metrics_manager.ts index 8df321bad..feac0b1f4 100644 --- a/core/flyout_metrics_manager.ts +++ b/core/flyout_metrics_manager.ts @@ -6,6 +6,7 @@ /** * Calculates and reports flyout workspace metrics. + * * @class */ import * as goog from '../closure/goog/goog.js'; @@ -19,6 +20,7 @@ import type {WorkspaceSvg} from './workspace_svg.js'; /** * Calculates metrics for a flyout's workspace. * The metrics are mainly used to size scrollbars for the flyout. + * * @alias Blockly.FlyoutMetricsManager */ export class FlyoutMetricsManager extends MetricsManager { @@ -37,7 +39,8 @@ export class FlyoutMetricsManager extends MetricsManager { /** * Gets the bounding box of the blocks on the flyout's workspace. * This is in workspace coordinates. - * @return The bounding box of the blocks on the workspace. + * + * @returns The bounding box of the blocks on the workspace. */ private getBoundingBox_(): SVGRect| {height: number, y: number, width: number, x: number} { diff --git a/core/generator.ts b/core/generator.ts index d3adaa6dd..a84568e8e 100644 --- a/core/generator.ts +++ b/core/generator.ts @@ -7,6 +7,7 @@ /** * Utility functions for generating executable code from * Blockly code. + * * @class */ import * as goog from '../closure/goog/goog.js'; @@ -21,6 +22,7 @@ import type {Workspace} from './workspace.js'; /** * Class for a code generator that translates the blocks into a language. + * * @unrestricted * @alias Blockly.Generator */ @@ -105,8 +107,9 @@ export class Generator { /** * Generate code for all blocks in the workspace to the specified language. + * * @param workspace Workspace to generate code from. - * @return Generated code. + * @returns Generated code. */ workspaceToCode(workspace?: Workspace): string { if (!workspace) { @@ -166,9 +169,10 @@ export class Generator { /** * Prepend a common prefix onto each line of code. * Intended for indenting code or adding comment markers. + * * @param text The lines of code. * @param prefix The common prefix. - * @return The prefixed lines of code. + * @returns The prefixed lines of code. */ prefixLines(text: string, prefix: string): string { return prefix + text.replace(/(?!\n$)\n/g, '\n' + prefix); @@ -176,8 +180,9 @@ export class Generator { /** * Recursively spider a tree of blocks, returning all their comments. + * * @param block The block from which to start spidering. - * @return Concatenated list of comments. + * @returns Concatenated list of comments. */ allNestedComments(block: Block): string { const comments = []; @@ -198,9 +203,10 @@ export class Generator { /** * Generate code for the specified block (and attached blocks). * The generator must be initialized before calling this function. + * * @param block The block to generate code for. * @param opt_thisOnly True to generate code for only this statement. - * @return For statement blocks, the generated code. + * @returns For statement blocks, the generated code. * For value blocks, an array containing the generated code and an * operator order value. Returns '' if block is null. */ @@ -257,11 +263,12 @@ export class Generator { /** * Generate code representing the specified value input. + * * @param block The block containing the input. * @param name The name of the input. * @param outerOrder The maximum binding strength (minimum order value) of any * operators adjacent to "block". - * @return Generated code or '' if no blocks are connected or the specified + * @returns Generated code or '' if no blocks are connected or the specified * input does not exist. */ valueToCode(block: Block, name: string, outerOrder: number): string { @@ -331,9 +338,10 @@ export class Generator { * statement input. Indent the code. * This is mainly used in generators. When trying to generate code to evaluate * look at using workspaceToCode or blockToCode. + * * @param block The block containing the input. * @param name The name of the input. - * @return Generated code or '' if no blocks are connected. + * @returns Generated code or '' if no blocks are connected. */ statementToCode(block: Block, name: string): string { const targetBlock = block.getInputTargetBlock(name); @@ -356,9 +364,10 @@ export class Generator { * Add statement suffix at the start of the loop block (right after the loop * statement executes), and a statement prefix to the end of the loop block * (right before the loop statement executes). + * * @param branch Code for loop contents. * @param block Enclosing block. - * @return Loop contents, with infinite loop trap added. + * @returns Loop contents, with infinite loop trap added. */ addLoopTrap(branch: string, block: Block): string { if (this.INFINITE_LOOP_TRAP) { @@ -382,9 +391,10 @@ export class Generator { /** * Inject a block ID into a message to replace '%1'. * Used for STATEMENT_PREFIX, STATEMENT_SUFFIX, and INFINITE_LOOP_TRAP. + * * @param msg Code snippet with '%1'. * @param block Block which has an ID. - * @return Code snippet with ID. + * @returns Code snippet with ID. */ injectId(msg: string, block: Block): string { const id = block.id.replace(/\$/g, '$$$$'); // Issue 251. @@ -393,6 +403,7 @@ export class Generator { /** * Add one or more words to the list of reserved words for this language. + * * @param words Comma-separated list of words to add to the list. * No spaces. Duplicates are ok. */ @@ -417,7 +428,7 @@ export class Generator { * @param desiredName The desired name of the function (e.g. mathIsPrime). * @param code A list of statements or one multi-line code string. Use ' ' * for indents (they will be replaced). - * @return The actual name of the new function. This may differ from + * @returns The actual name of the new function. This may differ from * desiredName if the former has already been taken by the user. */ protected provideFunction_(desiredName: string, code: string[]|string): @@ -450,6 +461,7 @@ export class Generator { * Hook for code to run before code generation starts. * Subclasses may override this, e.g. to initialise the database of variable * names. + * * @param _workspace Workspace to generate code from. */ init(_workspace: Workspace) { @@ -468,10 +480,11 @@ export class Generator { * Subclasses may override this, e.g. to generate code for statements * following the block, or to handle comments for the specified block and any * connected value blocks. + * * @param _block The current block. * @param code The code created for this block. * @param _opt_thisOnly True to generate code for only this statement. - * @return Code with comments and subsequent blocks added. + * @returns Code with comments and subsequent blocks added. */ protected scrub_(_block: Block, code: string, _opt_thisOnly?: boolean): string { @@ -483,8 +496,9 @@ export class Generator { * Hook for code to run at end of code generation. * Subclasses may override this, e.g. to prepend the generated code with * import statements or variable definitions. + * * @param code Generated code. - * @return Completed code. + * @returns Completed code. */ finish(code: string): string { // Optionally override @@ -499,8 +513,9 @@ export class Generator { * anything. * Subclasses may override this, e.g. if their language does not allow * naked values. + * * @param line Line of generated code. - * @return Legal line of code. + * @returns Legal line of code. */ scrubNakedValue(line: string): string { // Optionally override @@ -511,6 +526,7 @@ export class Generator { Object.defineProperties(Generator.prototype, { /** * A database of variable names. + * * @name Blockly.Generator.prototype.variableDB_ * @deprecated 'variableDB_' was renamed to 'nameDB_' (May 2021). * @suppress {checkTypes} @@ -518,14 +534,20 @@ Object.defineProperties(Generator.prototype, { // AnyDuringMigration because: Type 'Names | undefined' is not assignable to // type 'PropertyDescriptor'. variableDB_: ({ - /** @return Name database. */ + /** + * @param this + * @returns Name database. + */ get(this: Generator): Names | undefined { deprecation.warn( 'variableDB_', 'May 2021', 'September 2022', 'nameDB_'); return this.nameDB_; }, - /** @param nameDb New name database. */ + /** + * @param this + * @param nameDb New name database. + */ set(this: Generator, nameDb: Names|undefined) { deprecation.warn('variableDB_', 'May 2021', 'September2022', 'nameDB_'); this.nameDB_ = nameDb; diff --git a/core/input.ts b/core/input.ts index 86c235942..ed321a6ad 100644 --- a/core/input.ts +++ b/core/input.ts @@ -6,6 +6,7 @@ /** * Object representing an input (value, statement, or dummy). + * * @class */ import * as goog from '../closure/goog/goog.js'; @@ -25,6 +26,7 @@ import type {RenderedConnection} from './rendered_connection.js'; /** * Class for an input with an optional field. + * * @alias Blockly.Input */ export class Input { @@ -57,7 +59,8 @@ export class Input { /** * Get the source block for this input. - * @return The source block, or null if there is none. + * + * @returns The source block, or null if there is none. */ getSourceBlock(): Block { return this.sourceBlock_; @@ -66,10 +69,11 @@ export class Input { /** * Add a field (or label from string), and all prefix and suffix fields, to * the end of the input's field row. + * * @param field Something to add as a field. * @param opt_name Language-neutral identifier which may used to find this * field again. Should be unique to the host block. - * @return The input being append to (to allow chaining). + * @returns The input being append to (to allow chaining). */ appendField(field: string|Field, opt_name?: string): Input { this.insertFieldAt(this.fieldRow.length, field, opt_name); @@ -79,11 +83,12 @@ export class Input { /** * Inserts a field (or label from string), and all prefix and suffix fields, * at the location of the input's field row. + * * @param index The index at which to insert field. * @param field Something to add as a field. * @param opt_name Language-neutral identifier which may used to find this * field again. Should be unique to the host block. - * @return The index following the last inserted field. + * @returns The index following the last inserted field. */ insertFieldAt(index: number, field: string|Field, opt_name?: string): number { if (index < 0 || index > this.fieldRow.length) { @@ -133,9 +138,10 @@ export class Input { /** * Remove a field from this input. + * * @param name The name of the field. * @param opt_quiet True to prevent an error if field is not present. - * @return True if operation succeeds, false if field is not present and + * @returns True if operation succeeds, false if field is not present and * opt_quiet is true. * @throws {Error} if the field is not present and opt_quiet is false. */ @@ -160,7 +166,8 @@ export class Input { /** * Gets whether this input is visible or not. - * @return True if visible. + * + * @returns True if visible. */ isVisible(): boolean { return this.visible_; @@ -169,8 +176,9 @@ export class Input { /** * Sets whether this input is visible or not. * Should only be used to collapse/uncollapse a block. + * * @param visible True if visible. - * @return List of blocks to render. + * @returns List of blocks to render. * @internal */ setVisible(visible: boolean): BlockSvg[] { @@ -204,6 +212,7 @@ export class Input { /** * Mark all fields on this input as dirty. + * * @internal */ markDirty() { @@ -214,9 +223,10 @@ export class Input { /** * Change a connection's compatibility. + * * @param check Compatible value type or list of value types. Null if all * types are compatible. - * @return The input being modified (to allow chaining). + * @returns The input being modified (to allow chaining). */ setCheck(check: string|string[]|null): Input { if (!this.connection) { @@ -228,9 +238,10 @@ export class Input { /** * Change the alignment of the connection's field(s). + * * @param align One of the values of Align. In RTL mode directions * are reversed, and Align.RIGHT aligns to the left. - * @return The input being modified (to allow chaining). + * @returns The input being modified (to allow chaining). */ setAlign(align: Align): Input { this.align = align; @@ -243,8 +254,9 @@ export class Input { /** * Changes the connection's shadow block. + * * @param shadow DOM representation of a block or null. - * @return The input being modified (to allow chaining). + * @returns The input being modified (to allow chaining). */ setShadowDom(shadow: Element|null): Input { if (!this.connection) { @@ -256,7 +268,8 @@ export class Input { /** * Returns the XML representation of the connection's shadow block. - * @return Shadow DOM representation of a block or null. + * + * @returns Shadow DOM representation of a block or null. */ getShadowDom(): Element|null { if (!this.connection) { @@ -277,6 +290,7 @@ export class Input { /** * Sever all links to this input. + * * @suppress {checkTypes} */ dispose() { @@ -292,6 +306,7 @@ export class Input { export namespace Input { /** * Enum for alignment of inputs. + * * @alias Blockly.Input.Align */ export enum Align { diff --git a/core/input_types.ts b/core/input_types.ts index 30d2a620a..0ea695e89 100644 --- a/core/input_types.ts +++ b/core/input_types.ts @@ -6,6 +6,7 @@ /** * An enum for the possible types of inputs. + * * @namespace Blockly.inputTypes */ import * as goog from '../closure/goog/goog.js'; @@ -16,6 +17,7 @@ import {ConnectionType} from './connection_type.js'; /** * Enum for the type of a connection or input. + * * @alias Blockly.inputTypes */ export enum inputTypes { diff --git a/core/insertion_marker_manager.ts b/core/insertion_marker_manager.ts index 41d0dfcb9..31ccfa111 100644 --- a/core/insertion_marker_manager.ts +++ b/core/insertion_marker_manager.ts @@ -6,6 +6,7 @@ /** * Class that controls updates to connections during drags. + * * @class */ import * as goog from '../closure/goog/goog.js'; @@ -46,6 +47,7 @@ const DUPLICATE_BLOCK_ERROR = 'The insertion marker ' + * Class that controls updates to connections during drags. It is primarily * responsible for finding the closest eligible connection and highlighting or * unhighlighting it as needed during a drag. + * * @alias Blockly.InsertionMarkerManager */ export class InsertionMarkerManager { @@ -148,6 +150,7 @@ export class InsertionMarkerManager { /** * Sever all links from this object. + * * @internal */ dispose() { @@ -169,6 +172,7 @@ export class InsertionMarkerManager { /** * Update the available connections for the top block. These connections can * change if a block is unplugged and the stack is healed. + * * @internal */ updateAvailableConnections() { @@ -178,7 +182,8 @@ export class InsertionMarkerManager { /** * Return whether the block would be deleted if dropped immediately, based on * information from the most recent move event. - * @return True if the block would be deleted if dropped immediately. + * + * @returns True if the block would be deleted if dropped immediately. * @internal */ wouldDeleteBlock(): boolean { @@ -188,7 +193,8 @@ export class InsertionMarkerManager { /** * Return whether the block would be connected if dropped immediately, based * on information from the most recent move event. - * @return True if the block would be connected if dropped immediately. + * + * @returns True if the block would be connected if dropped immediately. * @internal */ wouldConnectBlock(): boolean { @@ -198,6 +204,7 @@ export class InsertionMarkerManager { /** * Connect to the closest connection and render the results. * This should be called at the end of a drag. + * * @internal */ applyConnections() { @@ -227,6 +234,7 @@ export class InsertionMarkerManager { /** * Update connections based on the most recent move location. + * * @param dxy Position relative to drag start, in workspace units. * @param dragTarget The drag target that the block is currently over. * @internal @@ -250,8 +258,9 @@ export class InsertionMarkerManager { /** * Create an insertion marker that represents the given block. + * * @param sourceBlock The block that the insertion marker will represent. - * @return The insertion marker that represents the given block. + * @returns The insertion marker that represents the given block. */ private createMarkerBlock_(sourceBlock: BlockSvg): BlockSvg { const imType = sourceBlock.type; @@ -311,7 +320,8 @@ export class InsertionMarkerManager { * should only be called once, at the beginning of a drag. If the stack has * more than one block, this function will populate lastOnStack_ and create * the corresponding insertion marker. - * @return A list of available connections. + * + * @returns A list of available connections. */ private initAvailableConnections_(): RenderedConnection[] { const available = this.topBlock_.getConnections_(false); @@ -336,10 +346,11 @@ export class InsertionMarkerManager { /** * Whether the previews (insertion marker and replacement marker) should be * updated based on the closest candidate and the current drag distance. + * * @param candidate An object containing a local connection, a closest * connection, and a radius. Returned by getCandidate_. * @param dxy Position relative to drag start, in workspace units. - * @return Whether the preview should be updated. + * @returns Whether the preview should be updated. */ private shouldUpdatePreviews_( candidate: CandidateConnection, dxy: Coordinate): boolean { @@ -386,8 +397,9 @@ export class InsertionMarkerManager { /** * Find the nearest valid connection, which may be the same as the current * closest connection. + * * @param dxy Position relative to drag start, in workspace units. - * @return An object containing a local connection, a closest connection, and + * @returns An object containing a local connection, a closest connection, and * a radius. */ private getCandidate_(dxy: Coordinate): CandidateConnection { @@ -420,7 +432,8 @@ export class InsertionMarkerManager { /** * Decide the radius at which to start searching for the closest connection. - * @return The radius at which to start the search for the closest connection. + * + * @returns The radius at which to start the search for the closest connection. */ private getStartRadius_(): number { // If there is already a connection highlighted, @@ -437,10 +450,11 @@ export class InsertionMarkerManager { /** * Whether ending the drag would delete the block. + * * @param candidate An object containing a local connection, a closest * connection, and a radius. * @param dragTarget The drag target that the block is currently over. - * @return Whether dropping the block immediately would delete the block. + * @returns Whether dropping the block immediately would delete the block. */ private shouldDelete_( candidate: CandidateConnection, dragTarget: IDragTarget|null): boolean { @@ -461,6 +475,7 @@ export class InsertionMarkerManager { * needed. * At the beginning of this function, this.localConnection_ and * this.closestConnection_ should both be null. + * * @param candidate An object containing a local connection, a closest * connection, and a radius. */ @@ -529,6 +544,7 @@ export class InsertionMarkerManager { * needed. * At the end of this function, this.localConnection_ and * this.closestConnection_ should both be null. + * * @param candidate An object containing a local connection, a closest * connection, and a radius. */ @@ -753,7 +769,8 @@ export class InsertionMarkerManager { /** * Get a list of the insertion markers that currently exist. Drags have 0, 1, * or 2 insertion markers. - * @return A possibly empty list of insertion marker blocks. + * + * @returns A possibly empty list of insertion marker blocks. * @internal */ getInsertionMarkers(): BlockSvg[] { diff --git a/core/keyboard_nav/ast_node.ts b/core/keyboard_nav/ast_node.ts index f668f8d41..899cac930 100644 --- a/core/keyboard_nav/ast_node.ts +++ b/core/keyboard_nav/ast_node.ts @@ -7,6 +7,7 @@ /** * The class representing an AST node. * Used to traverse the Blockly AST. + * * @class */ import * as goog from '../../closure/goog/goog.js'; @@ -27,6 +28,7 @@ import type {Workspace} from '../workspace.js'; * Class for an AST node. * It is recommended that you use one of the createNode methods instead of * creating a node directly. + * * @alias Blockly.ASTNode */ export class ASTNode { @@ -78,6 +80,7 @@ export class ASTNode { /** * Parse the optional parameters. + * * @param params The user specified parameters. */ private processParams_(params: Params|null) { @@ -93,7 +96,8 @@ export class ASTNode { * Gets the value pointed to by this node. * It is the callers responsibility to check the node type to figure out what * type of object they get back from this. - * @return The current field, connection, workspace, or block the cursor is + * + * @returns The current field, connection, workspace, or block the cursor is * on. */ getLocation(): IASTNodeLocation { @@ -103,7 +107,8 @@ export class ASTNode { /** * The type of the current location. * One of ASTNode.types - * @return The type of the location. + * + * @returns The type of the location. */ getType(): string { return this.type_; @@ -111,7 +116,8 @@ export class ASTNode { /** * The coordinate on the workspace. - * @return The workspace coordinate or null if the location is not a + * + * @returns The workspace coordinate or null if the location is not a * workspace. */ getWsCoordinate(): Coordinate { @@ -120,7 +126,8 @@ export class ASTNode { /** * Whether the node points to a connection. - * @return [description] + * + * @returns [description] * @internal */ isConnection(): boolean { @@ -131,7 +138,8 @@ export class ASTNode { * Given an input find the next editable field or an input with a non null * connection in the same block. The current location must be an input * connection. - * @return The AST node holding the next field or connection or null if there + * + * @returns The AST node holding the next field or connection or null if there * is no editable field or input connection after the given input. */ private findNextForInput_(): ASTNode|null { @@ -160,7 +168,8 @@ export class ASTNode { /** * Given a field find the next editable field or an input with a non null * connection in the same block. The current location must be a field. - * @return The AST node pointing to the next field or connection or null if + * + * @returns The AST node pointing to the next field or connection or null if * there is no editable field or input connection after the given input. */ private findNextForField_(): ASTNode|null { @@ -190,7 +199,8 @@ export class ASTNode { * Given an input find the previous editable field or an input with a non null * connection in the same block. The current location must be an input * connection. - * @return The AST node holding the previous field or connection. + * + * @returns The AST node holding the previous field or connection. */ private findPrevForInput_(): ASTNode|null { const location = this.location_ as Connection; @@ -218,7 +228,8 @@ export class ASTNode { /** * Given a field find the previous editable field or an input with a non null * connection in the same block. The current location must be a field. - * @return The AST node holding the previous input or field. + * + * @returns The AST node holding the previous input or field. */ private findPrevForField_(): ASTNode|null { const location = this.location_ as Field; @@ -249,8 +260,9 @@ export class ASTNode { /** * Navigate between stacks of blocks on the workspace. + * * @param forward True to go forward. False to go backwards. - * @return The first block of the next stack or null if there are no blocks on + * @returns The first block of the next stack or null if there are no blocks on * the workspace. */ private navigateBetweenStacks_(forward: boolean): ASTNode|null { @@ -287,8 +299,9 @@ export class ASTNode { * Finds the top most AST node for a given block. * This is either the previous connection, output connection or block * depending on what kind of connections the block has. + * * @param block The block that we want to find the top connection on. - * @return The AST node containing the top connection. + * @returns The AST node containing the top connection. */ private findTopASTNodeForBlock_(block: Block): ASTNode|null { const topConnection = getParentConnection(block); @@ -302,8 +315,9 @@ export class ASTNode { /** * Get the AST node pointing to the input that the block is nested under or if * the block is not nested then get the stack AST node. + * * @param block The source block of the current location. - * @return The AST node pointing to the input connection or the top block of + * @returns The AST node pointing to the input connection or the top block of * the stack this block is in. */ private getOutAstNodeForBlock_(block: Block): ASTNode|null { @@ -331,8 +345,9 @@ export class ASTNode { /** * Find the first editable field or input with a connection on a given block. + * * @param block The source block of the current location. - * @return An AST node pointing to the first field or input. + * @returns An AST node pointing to the first field or input. * Null if there are no editable fields or inputs with connections on the * block. */ @@ -356,7 +371,8 @@ export class ASTNode { /** * Finds the source block of the location of this node. - * @return The source block of the location, or null if the node is of type + * + * @returns The source block of the location, or null if the node is of type * workspace. */ getSourceBlock(): Block|null { @@ -373,7 +389,8 @@ export class ASTNode { /** * Find the element to the right of the current element in the AST. - * @return An AST node that wraps the next field, connection, block, or + * + * @returns An AST node that wraps the next field, connection, block, or * workspace. Or null if there is no node to the right. */ next(): ASTNode|null { @@ -413,7 +430,8 @@ export class ASTNode { /** * Find the element one level below and all the way to the left of the current * location. - * @return An AST node that wraps the next field, connection, workspace, or + * + * @returns An AST node that wraps the next field, connection, workspace, or * block. Or null if there is nothing below this node. */ in(): ASTNode|null { @@ -446,7 +464,8 @@ export class ASTNode { /** * Find the element to the left of the current element in the AST. - * @return An AST node that wraps the previous field, connection, workspace or + * + * @returns An AST node that wraps the previous field, connection, workspace or * block. Or null if no node exists to the left. * null. */ @@ -489,7 +508,8 @@ export class ASTNode { /** * Find the next element that is one position above and all the way to the * left of the current location. - * @return An AST node that wraps the next field, connection, workspace or + * + * @returns An AST node that wraps the next field, connection, workspace or * block. Or null if we are at the workspace level. */ out(): ASTNode|null { @@ -537,8 +557,9 @@ export class ASTNode { /** * Whether an AST node of the given type points to a connection. + * * @param type The type to check. One of ASTNode.types. - * @return True if a node of the given type points to a connection. + * @returns True if a node of the given type points to a connection. */ private static isConnectionType_(type: string): boolean { switch (type) { @@ -553,8 +574,9 @@ export class ASTNode { /** * Create an AST node pointing to a field. + * * @param field The location of the AST node. - * @return An AST node pointing to a field. + * @returns An AST node pointing to a field. */ static createFieldNode(field: Field): ASTNode|null { if (!field) { @@ -567,8 +589,9 @@ export class ASTNode { * Creates an AST node pointing to a connection. If the connection has a * parent input then create an AST node of type input that will hold the * connection. + * * @param connection This is the connection the node will point to. - * @return An AST node pointing to a connection. + * @returns An AST node pointing to a connection. */ static createConnectionNode(connection: Connection): ASTNode|null { if (!connection) { @@ -599,8 +622,9 @@ export class ASTNode { /** * Creates an AST node pointing to an input. Stores the input connection as * the location. + * * @param input The input used to create an AST node. - * @return An AST node pointing to a input. + * @returns An AST node pointing to a input. */ static createInputNode(input: Input): ASTNode|null { if (!input || !input.connection) { @@ -611,8 +635,9 @@ export class ASTNode { /** * Creates an AST node pointing to a block. + * * @param block The block used to create an AST node. - * @return An AST node pointing to a block. + * @returns An AST node pointing to a block. */ static createBlockNode(block: Block): ASTNode|null { if (!block) { @@ -625,9 +650,10 @@ export class ASTNode { * Create an AST node of type stack. A stack, represented by its top block, is * the set of all blocks connected to a top block, including the top * block. + * * @param topBlock A top block has no parent and can be found in the list * returned by workspace.getTopBlocks(). - * @return An AST node of type stack that points to the top block on the + * @returns An AST node of type stack that points to the top block on the * stack. */ static createStackNode(topBlock: Block): ASTNode|null { @@ -639,9 +665,10 @@ export class ASTNode { /** * Creates an AST node pointing to a workspace. + * * @param workspace The workspace that we are on. * @param wsCoordinate The position on the workspace for this node. - * @return An AST node pointing to a workspace and a position on the + * @returns An AST node pointing to a workspace and a position on the * workspace. */ static createWorkspaceNode( @@ -656,8 +683,9 @@ export class ASTNode { /** * Creates an AST node for the top position on a block. * This is either an output connection, previous connection, or block. + * * @param block The block to find the top most AST node on. - * @return The AST node holding the top most position on the block. + * @returns The AST node holding the top most position on the block. */ static createTopNode(block: Block): ASTNode|null { let astNode; @@ -699,8 +727,9 @@ export type Params = ASTNode.Params; * This is either an output connection, previous connection or undefined. * If both connections exist return the one that is actually connected * to another block. + * * @param block The block to find the parent connection on. - * @return The connection connecting to the parent of the block. + * @returns The connection connecting to the parent of the block. */ function getParentConnection(block: Block): Connection { let topConnection = block.outputConnection; diff --git a/core/keyboard_nav/basic_cursor.ts b/core/keyboard_nav/basic_cursor.ts index 7bbad93b6..434784587 100644 --- a/core/keyboard_nav/basic_cursor.ts +++ b/core/keyboard_nav/basic_cursor.ts @@ -7,6 +7,7 @@ /** * The class representing a basic cursor. * Used to demo switching between different cursors. + * * @class */ import * as goog from '../../closure/goog/goog.js'; @@ -22,6 +23,7 @@ import {Cursor} from './cursor.js'; * Class for a basic cursor. * This will allow the user to get to all nodes in the AST by hitting next or * previous. + * * @alias Blockly.BasicCursor */ export class BasicCursor extends Cursor { @@ -35,7 +37,8 @@ export class BasicCursor extends Cursor { /** * Find the next node in the pre order traversal. - * @return The next node, or null if the current node is not set or there is + * + * @returns The next node, or null if the current node is not set or there is * no next value. */ override next(): ASTNode|null { @@ -55,7 +58,8 @@ export class BasicCursor extends Cursor { * For a basic cursor we only have the ability to go next and previous, so * in will also allow the user to get to the next node in the pre order * traversal. - * @return The next node, or null if the current node is not set or there is + * + * @returns The next node, or null if the current node is not set or there is * no next value. */ override in(): ASTNode|null { @@ -64,7 +68,8 @@ export class BasicCursor extends Cursor { /** * Find the previous node in the pre order traversal. - * @return The previous node, or null if the current node is not set or there + * + * @returns The previous node, or null if the current node is not set or there * is no previous value. */ override prev(): ASTNode|null { @@ -84,7 +89,8 @@ export class BasicCursor extends Cursor { * For a basic cursor we only have the ability to go next and previous, so * out will allow the user to get to the previous node in the pre order * traversal. - * @return The previous node, or null if the current node is not set or there + * + * @returns The previous node, or null if the current node is not set or there * is no previous value. */ override out(): ASTNode|null { @@ -95,10 +101,11 @@ export class BasicCursor extends Cursor { * Uses pre order traversal to navigate the Blockly AST. This will allow * a user to easily navigate the entire Blockly AST without having to go in * and out levels on the tree. + * * @param node The current position in the AST. * @param isValid A function true/false depending on whether the given node * should be traversed. - * @return The next node in the traversal. + * @returns The next node in the traversal. */ protected getNextNode_( node: ASTNode|null, isValid: (p1: ASTNode|null) => boolean): ASTNode @@ -127,10 +134,11 @@ export class BasicCursor extends Cursor { * Reverses the pre order traversal in order to find the previous node. This * will allow a user to easily navigate the entire Blockly AST without having * to go in and out levels on the tree. + * * @param node The current position in the AST. * @param isValid A function true/false depending on whether the given node * should be traversed. - * @return The previous node in the traversal or null if no previous node + * @returns The previous node in the traversal or null if no previous node * exists. */ protected getPreviousNode_( @@ -157,8 +165,9 @@ export class BasicCursor extends Cursor { /** * Decides what nodes to traverse and which ones to skip. Currently, it * skips output, stack and workspace nodes. + * * @param node The AST node to check whether it is valid. - * @return True if the node should be visited, false otherwise. + * @returns True if the node should be visited, false otherwise. */ protected validNode_(node: ASTNode|null): boolean { let isValid = false; @@ -173,8 +182,9 @@ export class BasicCursor extends Cursor { /** * From the given node find either the next valid sibling or parent. + * * @param node The current position in the AST. - * @return The parent AST node or null if there are no valid parents. + * @returns The parent AST node or null if there are no valid parents. */ private findSiblingOrParent_(node: ASTNode|null): ASTNode|null { if (!node) { @@ -189,8 +199,9 @@ export class BasicCursor extends Cursor { /** * Get the right most child of a node. + * * @param node The node to find the right most child of. - * @return The right most child of the given node, or the node if no child + * @returns The right most child of the given node, or the node if no child * exists. */ private getRightMostChild_(node: ASTNode|null): ASTNode|null { diff --git a/core/keyboard_nav/cursor.ts b/core/keyboard_nav/cursor.ts index ca3653e8d..812cd723f 100644 --- a/core/keyboard_nav/cursor.ts +++ b/core/keyboard_nav/cursor.ts @@ -7,6 +7,7 @@ /** * The class representing a cursor. * Used primarily for keyboard navigation. + * * @class */ import * as goog from '../../closure/goog/goog.js'; @@ -21,6 +22,7 @@ import {Marker} from './marker.js'; /** * Class for a cursor. * A cursor controls how a user navigates the Blockly AST. + * * @alias Blockly.Cursor */ export class Cursor extends Marker { @@ -33,7 +35,8 @@ export class Cursor extends Marker { /** * Find the next connection, field, or block. - * @return The next element, or null if the current node is not set or there + * + * @returns The next element, or null if the current node is not set or there * is no next value. */ next(): ASTNode|null { @@ -57,7 +60,8 @@ export class Cursor extends Marker { /** * Find the in connection or field. - * @return The in element, or null if the current node is not set or there is + * + * @returns The in element, or null if the current node is not set or there is * no in value. */ in(): ASTNode|null { @@ -81,7 +85,8 @@ export class Cursor extends Marker { /** * Find the previous connection, field, or block. - * @return The previous element, or null if the current node is not set or + * + * @returns The previous element, or null if the current node is not set or * there is no previous value. */ prev(): ASTNode|null { @@ -105,7 +110,8 @@ export class Cursor extends Marker { /** * Find the out connection, field, or block. - * @return The out element, or null if the current node is not set or there is + * + * @returns The out element, or null if the current node is not set or there is * no out value. */ out(): ASTNode|null { diff --git a/core/keyboard_nav/marker.ts b/core/keyboard_nav/marker.ts index c76b14e1e..725bc26e3 100644 --- a/core/keyboard_nav/marker.ts +++ b/core/keyboard_nav/marker.ts @@ -7,6 +7,7 @@ /** * The class representing a marker. * Used primarily for keyboard navigation to show a marked location. + * * @class */ import * as goog from '../../closure/goog/goog.js'; @@ -21,6 +22,7 @@ import type {ASTNode} from './ast_node.js'; /** * Class for a marker. * This is used in keyboard navigation to save a location in the Blockly AST. + * * @alias Blockly.Marker */ export class Marker { @@ -48,6 +50,7 @@ export class Marker { /** * Sets the object in charge of drawing the marker. + * * @param drawer The object in charge of drawing the marker. */ setDrawer(drawer: MarkerSvg) { @@ -56,7 +59,8 @@ export class Marker { /** * Get the current drawer for the marker. - * @return The object in charge of drawing the marker. + * + * @returns The object in charge of drawing the marker. */ getDrawer(): MarkerSvg { return this.drawer_; @@ -64,7 +68,8 @@ export class Marker { /** * Gets the current location of the marker. - * @return The current field, connection, or block the marker is on. + * + * @returns The current field, connection, or block the marker is on. */ getCurNode(): ASTNode { return this.curNode_; @@ -74,6 +79,7 @@ export class Marker { * Set the location of the marker and call the update method. * Setting isStack to true will only work if the newLocation is the top most * output or previous connection on a stack. + * * @param newNode The new location of the marker. */ setCurNode(newNode: ASTNode) { @@ -86,6 +92,7 @@ export class Marker { /** * Redraw the current marker. + * * @internal */ draw() { diff --git a/core/keyboard_nav/tab_navigate_cursor.ts b/core/keyboard_nav/tab_navigate_cursor.ts index 26bb9b0f2..588ddede5 100644 --- a/core/keyboard_nav/tab_navigate_cursor.ts +++ b/core/keyboard_nav/tab_navigate_cursor.ts @@ -7,6 +7,7 @@ /** * The class representing a cursor that is used to navigate * between tab navigable fields. + * * @class */ import * as goog from '../../closure/goog/goog.js'; @@ -20,13 +21,15 @@ import {BasicCursor} from './basic_cursor.js'; /** * A cursor for navigating between tab navigable fields. + * * @alias Blockly.TabNavigateCursor */ export class TabNavigateCursor extends BasicCursor { /** * Skip all nodes except for tab navigable fields. + * * @param node The AST node to check whether it is valid. - * @return True if the node should be visited, false otherwise. + * @returns True if the node should be visited, false otherwise. */ override validNode_(node: ASTNode|null): boolean { let isValid = false; diff --git a/core/marker_manager.ts b/core/marker_manager.ts index 2a6d16dbf..6bc928c1b 100644 --- a/core/marker_manager.ts +++ b/core/marker_manager.ts @@ -6,6 +6,7 @@ /** * Object in charge of managing markers and the cursor. + * * @class */ import * as goog from '../closure/goog/goog.js'; @@ -18,6 +19,7 @@ import type {WorkspaceSvg} from './workspace_svg.js'; /** * Class to manage the multiple markers and the cursor on a workspace. + * * @alias Blockly.MarkerManager */ export class MarkerManager { @@ -44,6 +46,7 @@ export class MarkerManager { /** * Register the marker by adding it to the map of markers. + * * @param id A unique identifier for the marker. * @param marker The marker to register. */ @@ -59,6 +62,7 @@ export class MarkerManager { /** * Unregister the marker by removing it from the map of markers. + * * @param id The ID of the marker to unregister. */ unregisterMarker(id: string) { @@ -75,7 +79,8 @@ export class MarkerManager { /** * Get the cursor for the workspace. - * @return The cursor for this workspace. + * + * @returns The cursor for this workspace. */ getCursor(): Cursor|null { return this.cursor_; @@ -83,8 +88,9 @@ export class MarkerManager { /** * Get a single marker that corresponds to the given ID. + * * @param id A unique identifier for the marker. - * @return The marker that corresponds to the given ID, or null if none + * @returns The marker that corresponds to the given ID, or null if none * exists. */ getMarker(id: string): Marker|null { @@ -94,6 +100,7 @@ export class MarkerManager { /** * Sets the cursor and initializes the drawer for use with keyboard * navigation. + * * @param cursor The cursor used to move around this workspace. */ setCursor(cursor: Cursor) { @@ -111,6 +118,7 @@ export class MarkerManager { /** * Add the cursor SVG to this workspace SVG group. + * * @param cursorSvg The SVG root of the cursor to be added to the workspace * SVG group. * @internal @@ -127,6 +135,7 @@ export class MarkerManager { /** * Add the marker SVG to this workspaces SVG group. + * * @param markerSvg The SVG root of the marker to be added to the workspace * SVG group. * @internal @@ -149,6 +158,7 @@ export class MarkerManager { /** * Redraw the attached cursor SVG if needed. + * * @internal */ updateMarkers() { @@ -160,6 +170,7 @@ export class MarkerManager { /** * Dispose of the marker manager. * Go through and delete all markers associated with this marker manager. + * * @suppress {checkTypes} * @internal */ diff --git a/core/menu.ts b/core/menu.ts index 57e9e0ad7..1dc5d7dea 100644 --- a/core/menu.ts +++ b/core/menu.ts @@ -6,6 +6,7 @@ /** * Blockly menu similar to Closure's goog.ui.Menu + * * @class */ import * as goog from '../closure/goog/goog.js'; @@ -23,6 +24,7 @@ import * as style from './utils/style.js'; /** * A basic menu class. + * * @alias Blockly.Menu */ export class Menu { @@ -72,6 +74,7 @@ export class Menu { /** * Add a new menu item to the bottom of this menu. + * * @param menuItem Menu item to append. * @internal */ @@ -81,6 +84,7 @@ export class Menu { /** * Creates the menu DOM. + * * @param container Element upon which to append this menu. */ render(container: Element) { @@ -115,7 +119,8 @@ export class Menu { /** * Gets the menu's element. - * @return The DOM element. + * + * @returns The DOM element. * @internal */ getElement(): Element|null { @@ -124,6 +129,7 @@ export class Menu { /** * Focus the menu element. + * * @internal */ focus() { @@ -149,6 +155,7 @@ export class Menu { /** * Set the menu accessibility role. + * * @param roleName role name. * @internal */ @@ -192,8 +199,9 @@ export class Menu { /** * Returns the child menu item that owns the given DOM element, * or null if no such menu item is found. + * * @param elem DOM element whose owner is to be returned. - * @return Menu item for which the DOM element belongs to. + * @returns Menu item for which the DOM element belongs to. */ private getMenuItem_(elem: Element): MenuItem|null { const menuElem = this.getElement(); @@ -221,6 +229,7 @@ export class Menu { /** * Highlights the given menu item, or clears highlighting if null. + * * @param item Item to highlight, or null. * @internal */ @@ -245,6 +254,7 @@ export class Menu { /** * Highlights the next highlightable item (or the first if nothing is * currently highlighted). + * * @internal */ highlightNext() { @@ -258,6 +268,7 @@ export class Menu { /** * Highlights the previous highlightable item (or the last if nothing is * currently highlighted). + * * @internal */ highlightPrevious() { @@ -281,6 +292,7 @@ export class Menu { /** * Helper function that manages the details of moving the highlight among * child menuitems in response to keyboard events. + * * @param startIndex Start index. * @param delta Step direction: 1 to go down, -1 to go up. */ @@ -300,6 +312,7 @@ export class Menu { /** * Handles mouseover events. Highlight menuitems as the user hovers over them. + * * @param e Mouse event to handle. */ private handleMouseOver_(e: Event) { @@ -318,6 +331,7 @@ export class Menu { /** * Handles click events. Pass the event onto the child menuitem to handle. + * * @param e Click event to handle. */ private handleClick_(e: Event) { @@ -350,6 +364,7 @@ export class Menu { /** * Handles mouse enter events. Focus the element. + * * @param _e Mouse event to handle. */ private handleMouseEnter_(_e: Event) { @@ -358,6 +373,7 @@ export class Menu { /** * Handles mouse leave events. Blur and clear highlight. + * * @param _e Mouse event to handle. */ private handleMouseLeave_(_e: Event) { @@ -373,6 +389,7 @@ export class Menu { * Attempts to handle a keyboard event, if the menu item is enabled, by * calling * {@link handleKeyEventInternal_}. + * * @param e Key event to handle. */ private handleKeyEvent_(e: Event) { @@ -432,7 +449,8 @@ export class Menu { /** * Get the size of a rendered menu. - * @return Object with width and height properties. + * + * @returns Object with width and height properties. * @internal */ getSize(): Size { diff --git a/core/menuitem.ts b/core/menuitem.ts index 6182ea684..6af0ff84e 100644 --- a/core/menuitem.ts +++ b/core/menuitem.ts @@ -6,6 +6,7 @@ /** * Blockly menu item similar to Closure's goog.ui.MenuItem + * * @class */ import * as goog from '../closure/goog/goog.js'; @@ -18,6 +19,7 @@ import * as idGenerator from './utils/idgenerator.js'; /** * Class representing an item in a menu. + * * @alias Blockly.MenuItem */ export class MenuItem { @@ -56,7 +58,8 @@ export class MenuItem { /** * Creates the menuitem's DOM. - * @return Completed DOM. + * + * @returns Completed DOM. */ createDom(): Element { const element = (document.createElement('div')); @@ -108,7 +111,8 @@ export class MenuItem { /** * Gets the menu item's element. - * @return The DOM element. + * + * @returns The DOM element. * @internal */ getElement(): Element|null { @@ -117,7 +121,8 @@ export class MenuItem { /** * Gets the unique ID for this menu item. - * @return Unique component ID. + * + * @returns Unique component ID. * @internal */ getId(): string { @@ -126,7 +131,8 @@ export class MenuItem { /** * Gets the value associated with the menu item. - * @return value Value associated with the menu item. + * + * @returns value Value associated with the menu item. * @internal */ getValue(): AnyDuringMigration { @@ -135,6 +141,7 @@ export class MenuItem { /** * Set menu item's rendering direction. + * * @param rtl True if RTL, false if LTR. * @internal */ @@ -144,6 +151,7 @@ export class MenuItem { /** * Set the menu item's accessibility role. + * * @param roleName Role name. * @internal */ @@ -154,6 +162,7 @@ export class MenuItem { /** * Sets the menu item to be checkable or not. Set to true for menu items * that represent checkable options. + * * @param checkable Whether the menu item is checkable. * @internal */ @@ -163,6 +172,7 @@ export class MenuItem { /** * Checks or unchecks the component. + * * @param checked Whether to check or uncheck the component. * @internal */ @@ -172,6 +182,7 @@ export class MenuItem { /** * Highlights or unhighlights the component. + * * @param highlight Whether to highlight or unhighlight the component. * @internal */ @@ -196,7 +207,8 @@ export class MenuItem { /** * Returns true if the menu item is enabled, false otherwise. - * @return Whether the menu item is enabled. + * + * @returns Whether the menu item is enabled. * @internal */ isEnabled(): boolean { @@ -205,6 +217,7 @@ export class MenuItem { /** * Enables or disables the menu item. + * * @param enabled Whether to enable or disable the menu item. * @internal */ @@ -215,6 +228,7 @@ export class MenuItem { /** * Performs the appropriate action when the menu item is activated * by the user. + * * @internal */ performAction() { @@ -226,6 +240,7 @@ export class MenuItem { /** * Set the handler that's called when the menu item is activated by the user. * `obj` will be used as the 'this' object in the function when called. + * * @param fn The handler. * @param obj Used as the 'this' object in fn when called. * @internal diff --git a/core/mutator.ts b/core/mutator.ts index a143e56fd..9acfa9bbf 100644 --- a/core/mutator.ts +++ b/core/mutator.ts @@ -7,6 +7,7 @@ /** * Object representing a mutator dialog. A mutator allows the * user to change the shape of a block using a nested blocks editor. + * * @class */ import * as goog from '../closure/goog/goog.js'; @@ -36,6 +37,7 @@ import type {WorkspaceSvg} from './workspace_svg.js'; /** * Class for a mutator dialog. + * * @alias Blockly.Mutator */ export class Mutator extends Icon { @@ -74,7 +76,10 @@ export class Mutator extends Icon { */ private updateWorkspacePid_: AnyDuringMigration = 0; - /** @param quarkNames List of names of sub-blocks for flyout. */ + /** + * @param block + * @param quarkNames List of names of sub-blocks for flyout. + */ constructor(block: BlockSvg, quarkNames: string[]) { super(block); this.quarkNames_ = quarkNames; @@ -82,6 +87,7 @@ export class Mutator extends Icon { /** * Set the block this mutator is associated with. + * * @param block The block associated with this mutator. * @internal */ @@ -91,7 +97,8 @@ export class Mutator extends Icon { /** * Returns the workspace inside this mutator icon's bubble. - * @return The workspace inside this mutator icon's bubble or null if the + * + * @returns The workspace inside this mutator icon's bubble or null if the * mutator isn't open. * @internal */ @@ -101,6 +108,7 @@ export class Mutator extends Icon { /** * Draw the mutator icon. + * * @param group The icon group. */ protected override drawIcon_(group: Element) { @@ -136,6 +144,7 @@ export class Mutator extends Icon { /** * Clicking on the icon toggles if the mutator bubble is visible. * Disable if block is uneditable. + * * @param e Mouse click event. */ protected override iconClick_(e: MouseEvent) { @@ -146,7 +155,8 @@ export class Mutator extends Icon { /** * Create the editor for the mutator's bubble. - * @return The top-level node of the editor. + * + * @returns The top-level node of the editor. */ private createEditor_(): SVGElement { /* Create the editor. Here's the markup that will be generated: @@ -210,6 +220,7 @@ export class Mutator extends Icon { } /** + * @param options * @internal */ // eslint-disable-next-line @typescript-eslint/no-unused-vars @@ -294,6 +305,7 @@ export class Mutator extends Icon { /** * Show or hide the mutator bubble. + * * @param visible True if the bubble should be visible. */ override setVisible(visible: boolean) { @@ -376,6 +388,7 @@ export class Mutator extends Icon { /** * Fired whenever a change is made to the mutator's workspace. + * * @param e Custom data for event. */ private workspaceChanged_(e: Abstract) { @@ -390,8 +403,9 @@ export class Mutator extends Icon { /** * Returns whether the given event in the mutator workspace should be ignored * when deciding whether to update the workspace and compose the block or not. + * * @param e The event. - * @return Whether to ignore the event or not. + * @returns Whether to ignore the event or not. */ shouldIgnoreMutatorEvent_(e: Abstract) { return e.isUiEvent || e.type === eventUtils.CREATE || @@ -507,10 +521,11 @@ export class Mutator extends Icon { /** * Reconnect an block to a mutated input. + * * @param connectionChild Connection on child block. * @param block Parent block. * @param inputName Name of input on parent block. - * @return True iff a reconnection was made, false otherwise. + * @returns True iff a reconnection was made, false otherwise. */ static reconnect( connectionChild: Connection, block: Block, inputName: string): boolean { @@ -534,8 +549,9 @@ export class Mutator extends Icon { /** * Get the parent workspace of a workspace that is inside a mutator, taking * into account whether it is a flyout. + * * @param workspace The workspace that is inside a mutator. - * @return The mutator's parent workspace or null. + * @returns The mutator's parent workspace or null. */ static findParentWs(workspace: WorkspaceSvg): WorkspaceSvg|null { let outerWs = null; diff --git a/core/names.ts b/core/names.ts index 5eb95fb38..10892f990 100644 --- a/core/names.ts +++ b/core/names.ts @@ -6,6 +6,7 @@ /** * Utility functions for handling variable and procedure names. + * * @class */ import * as goog from '../closure/goog/goog.js'; @@ -23,6 +24,7 @@ import type {Workspace} from './workspace.js'; /** * Class for a database of entity names (variables, procedures, etc). + * * @alias Blockly.Names */ export class Names { @@ -71,6 +73,7 @@ export class Names { /** * Set the variable map that maps from variable name to variable object. + * * @param map The map to track. */ setVariableMap(map: VariableMap) { @@ -80,8 +83,9 @@ export class Names { /** * Get the name for a user-defined variable, based on its ID. * This should only be used for variables of NameType VARIABLE. + * * @param id The ID to look up in the variable map. - * @return The name of the referenced variable, or null if there was no + * @returns The name of the referenced variable, or null if there was no * variable map or the variable was not found in the map. */ private getNameForUserVariable_(id: string): string|null { @@ -103,6 +107,7 @@ export class Names { /** * Generate names for user variables, but only ones that are being used. + * * @param workspace Workspace to generate variables from. */ populateVariables(workspace: Workspace) { @@ -114,6 +119,7 @@ export class Names { /** * Generate names for procedures. + * * @param workspace Workspace to generate procedures from. */ // eslint-disable-next-line @typescript-eslint/no-unused-vars @@ -125,10 +131,11 @@ export class Names { /** * Convert a Blockly entity name to a legal exportable entity name. + * * @param nameOrId The Blockly entity name (no constraints) or variable ID. * @param type The type of the name in Blockly ('VARIABLE', 'PROCEDURE', * 'DEVELOPER_VARIABLE', etc...). - * @return An entity name that is legal in the exported language. + * @returns An entity name that is legal in the exported language. */ getName(nameOrId: string, type: NameType|string): string { let name = nameOrId; @@ -159,9 +166,10 @@ export class Names { /** * Return a list of all known user-created names of a specified name type. + * * @param type The type of entity in Blockly ('VARIABLE', 'PROCEDURE', * 'DEVELOPER_VARIABLE', etc...). - * @return A list of Blockly entity names (no constraints). + * @returns A list of Blockly entity names (no constraints). */ getUserNames(type: NameType|string): string[] { const userNames = this.db.get(type)?.keys(); @@ -173,10 +181,11 @@ export class Names { * Ensure that this is a new name not overlapping any previously defined name. * Also check against list of reserved words for the current language and * ensure name doesn't collide. + * * @param name The Blockly entity name (no constraints). * @param type The type of entity in Blockly ('VARIABLE', 'PROCEDURE', * 'DEVELOPER_VARIABLE', etc...). - * @return An entity name that is legal in the exported language. + * @returns An entity name that is legal in the exported language. */ getDistinctName(name: string, type: NameType|string): string { let safeName = this.safeName_(name); @@ -200,8 +209,9 @@ export class Names { * Given a proposed entity name, generate a name that conforms to the * [_A-Za-z][_A-Za-z0-9]* format that most languages consider legal for * variable and function names. + * * @param name Potentially illegal entity name. - * @return Safe entity name. + * @returns Safe entity name. */ private safeName_(name: string): string { if (!name) { @@ -222,9 +232,10 @@ export class Names { /** * Do the given two entity names refer to the same entity? * Blockly names are case-insensitive. + * * @param name1 First name. * @param name2 Second name. - * @return True if names are the same. + * @returns True if names are the same. */ static equals(name1: string, name2: string): boolean { // name1.localeCompare(name2) is slower. @@ -242,6 +253,7 @@ export namespace Names { * Therefore, Blockly keeps a separate name type to disambiguate. * getName('foo', 'VARIABLE') -> 'foo' * getName('foo', 'PROCEDURE') -> 'foo2' + * * @alias Blockly.Names.NameType */ export enum NameType { diff --git a/core/positionable_helpers.ts b/core/positionable_helpers.ts index 6a957b324..937806379 100644 --- a/core/positionable_helpers.ts +++ b/core/positionable_helpers.ts @@ -6,6 +6,7 @@ /** * Utility functions for positioning UI elements. + * * @namespace Blockly.uiPosition */ import * as goog from '../closure/goog/goog.js'; @@ -25,6 +26,7 @@ import type {WorkspaceSvg} from './workspace_svg.js'; /** * Enum for vertical positioning. + * * @alias Blockly.uiPosition.verticalPosition * @internal */ @@ -35,6 +37,7 @@ export enum verticalPosition { /** * Enum for horizontal positioning. + * * @alias Blockly.uiPosition.horizontalPosition * @internal */ @@ -45,6 +48,7 @@ export enum horizontalPosition { /** * An object defining a horizontal and vertical positioning. + * * @alias Blockly.uiPosition.Position * @internal */ @@ -55,6 +59,7 @@ export interface Position { /** * Enum for bump rules to use for dealing with collisions. + * * @alias Blockly.uiPosition.bumpDirection * @internal */ @@ -68,13 +73,14 @@ export enum bumpDirection { * element of the specified size given the restraints and locations of the * scrollbars. This method does not take into account any already placed UI * elements. + * * @param position The starting horizontal and vertical position. * @param size the size of the UI element to get a start position for. * @param horizontalPadding The horizontal padding to use. * @param verticalPadding The vertical padding to use. * @param metrics The workspace UI metrics. * @param workspace The workspace. - * @return The suggested start position. + * @returns The suggested start position. * @alias Blockly.uiPosition.getStartPositionRect * @internal */ @@ -118,9 +124,10 @@ export function getStartPositionRect( * the toolbox. * If in horizontal orientation, defaults to the bottom corner. If in vertical * orientation, defaults to the right corner. + * * @param workspace The workspace. * @param metrics The workspace metrics. - * @return The suggested corner position. + * @returns The suggested corner position. * @alias Blockly.uiPosition.getCornerOppositeToolbox * @internal */ @@ -140,13 +147,14 @@ export function getCornerOppositeToolbox( * Returns a position Rect based on a starting position that is bumped * so that it doesn't intersect with any of the provided savedPositions. This * method does not check that the bumped position is still within bounds. + * * @param startRect The starting position to use. * @param margin The margin to use between elements when bumping. * @param bumpDir The direction to bump if there is a collision with an existing * UI element. * @param savedPositions List of rectangles that represent the positions of UI * elements already placed. - * @return The suggested position rectangle. + * @returns The suggested position rectangle. * @alias Blockly.uiPosition.bumpPositionRect * @internal */ diff --git a/core/procedures.ts b/core/procedures.ts index e0b1db6e6..2ad135395 100644 --- a/core/procedures.ts +++ b/core/procedures.ts @@ -6,6 +6,7 @@ /** * Utility functions for handling procedures. + * * @namespace Blockly.Procedures */ import * as goog from '../closure/goog/goog.js'; @@ -37,18 +38,21 @@ import * as Xml from './xml.js'; * procedure blocks. * See also Blockly.Variables.CATEGORY_NAME and * Blockly.VariablesDynamic.CATEGORY_NAME. + * * @alias Blockly.Procedures.CATEGORY_NAME */ export const CATEGORY_NAME = 'PROCEDURE'; /** * The default argument for a procedures_mutatorarg block. + * * @alias Blockly.Procedures.DEFAULT_ARG */ export const DEFAULT_ARG = 'x'; /** * Procedure block type. + * * @alias Blockly.Procedures.ProcedureBlock */ export interface ProcedureBlock { @@ -59,8 +63,9 @@ export interface ProcedureBlock { /** * Find all user-created procedure definitions in a workspace. + * * @param root Root workspace. - * @return Pair of arrays, the first contains procedures without return + * @returns Pair of arrays, the first contains procedures without return * variables, the second with. Each procedure is defined by a three-element * list of name, parameter list, and return value boolean. * @alias Blockly.Procedures.allProcedures @@ -83,9 +88,10 @@ export function allProcedures(root: Workspace): AnyDuringMigration[][][] { /** * Comparison function for case-insensitive sorting of the first element of * a tuple. + * * @param ta First tuple. * @param tb Second tuple. - * @return -1, 0, or 1 to signify greater than, equality, or less than. + * @returns -1, 0, or 1 to signify greater than, equality, or less than. */ function procTupleComparator( ta: AnyDuringMigration[], tb: AnyDuringMigration[]): number { @@ -96,9 +102,10 @@ function procTupleComparator( * Ensure two identically-named procedures don't exist. * Take the proposed procedure name, and return a legal name i.e. one that * is not empty and doesn't collide with other procedures. + * * @param name Proposed procedure name. * @param block Block to disambiguate. - * @return Non-colliding name. + * @returns Non-colliding name. * @alias Blockly.Procedures.findLegalName */ export function findLegalName(name: string, block: Block): string { @@ -121,11 +128,12 @@ export function findLegalName(name: string, block: Block): string { /** * Does this procedure have a legal name? Illegal names include names of * procedures already defined. + * * @param name The questionable name. * @param workspace The workspace to scan for collisions. * @param opt_exclude Optional block to exclude from comparisons (one doesn't * want to collide with oneself). - * @return True if the name is legal. + * @returns True if the name is legal. */ function isLegalName( name: string, workspace: Workspace, opt_exclude?: Block): boolean { @@ -134,11 +142,12 @@ function isLegalName( /** * Return if the given name is already a procedure name. + * * @param name The questionable name. * @param workspace The workspace to scan for collisions. * @param opt_exclude Optional block to exclude from comparisons (one doesn't * want to collide with oneself). - * @return True if the name is used, otherwise return false. + * @returns True if the name is used, otherwise return false. * @alias Blockly.Procedures.isNameUsed */ export function isNameUsed( @@ -163,8 +172,10 @@ export function isNameUsed( /** * Rename a procedure. Called by the editable field. + * + * @param this * @param name The proposed new name. - * @return The accepted name. + * @returns The accepted name. * @alias Blockly.Procedures.rename */ export function rename(this: Field, name: string): string { @@ -189,8 +200,9 @@ export function rename(this: Field, name: string): string { /** * Construct the blocks required by the flyout for the procedure category. + * * @param workspace The workspace containing procedures. - * @return Array of XML block elements. + * @returns Array of XML block elements. * @alias Blockly.Procedures.flyoutCategory */ export function flyoutCategory(workspace: WorkspaceSvg): Element[] { @@ -245,6 +257,7 @@ export function flyoutCategory(workspace: WorkspaceSvg): Element[] { /** * Add items to xmlList for each listed procedure. + * * @param procedureList A list of procedures, each of which is defined by a * three-element list of name, parameter list, and return value boolean. * @param templateName The type of the block to generate. @@ -287,6 +300,7 @@ export function flyoutCategory(workspace: WorkspaceSvg): Element[] { /** * Updates the procedure mutator's flyout so that the arg block is not a * duplicate of another arg. + * * @param workspace The procedure mutator's workspace. This workspace's flyout * is what is being updated. */ @@ -316,6 +330,7 @@ function updateMutatorFlyout(workspace: WorkspaceSvg) { /** * Listens for when a procedure mutator is opened. Then it triggers a flyout * update and adds a mutator change listener to the mutator workspace. + * * @param e The event that triggered this listener. * @alias Blockly.Procedures.mutatorOpenListener * @internal @@ -343,6 +358,7 @@ export function mutatorOpenListener(e: Abstract) { /** * Listens for changes in a procedure mutator and triggers flyout updates when * necessary. + * * @param e The event that triggered this listener. */ function mutatorChangeListener(e: Abstract) { @@ -358,9 +374,10 @@ function mutatorChangeListener(e: Abstract) { /** * Find all the callers of a named procedure. + * * @param name Name of procedure. * @param workspace The workspace to find callers in. - * @return Array of caller blocks. + * @returns Array of caller blocks. * @alias Blockly.Procedures.getCallers */ export function getCallers(name: string, workspace: Workspace): Block[] { @@ -384,6 +401,7 @@ export function getCallers(name: string, workspace: Workspace): Block[] { /** * When a procedure definition changes its parameters, find and edit all its * callers. + * * @param defBlock Procedure definition block. * @alias Blockly.Procedures.mutateCallers */ @@ -415,9 +433,10 @@ export function mutateCallers(defBlock: Block) { /** * Find the definition block for the named procedure. + * * @param name Name of procedure. * @param workspace The workspace to search. - * @return The procedure definition block, or null not found. + * @returns The procedure definition block, or null not found. * @alias Blockly.Procedures.getDefinition */ export function getDefinition(name: string, workspace: Workspace): Block|null { diff --git a/core/registry.ts b/core/registry.ts index 96c40d004..a31241180 100644 --- a/core/registry.ts +++ b/core/registry.ts @@ -7,6 +7,7 @@ /** * This file is a universal registry that provides generic methods * for registering and unregistering different types of classes. + * * @namespace Blockly.registry */ import * as goog from '../closure/goog/goog.js'; @@ -47,12 +48,14 @@ const nameMap: {[key: string]: {[key: string]: string}} = Object.create(null); /** * The string used to register the default class for a type of plugin. + * * @alias Blockly.registry.DEFAULT */ export const DEFAULT = 'default'; /** * A name with the type of the element stored in the generic. + * * @alias Blockly.registry.Type */ export class Type<_T> { @@ -61,7 +64,8 @@ export class Type<_T> { /** * Returns the name of the type. - * @return The name. + * + * @returns The name. */ toString(): string { return this.name; @@ -98,6 +102,7 @@ export class Type<_T> { /** * Registers a class based on a type and name. + * * @param type The type of the plugin. * (e.g. Field, Renderer) * @param name The plugin's name. (Ex. field_angle, geras) @@ -155,6 +160,7 @@ export function register( /** * Checks the given registry item for properties that are required based on the * type. + * * @param type The type of the plugin. (e.g. Field, Renderer) * @param registryItem A class or object that we are checking for the required * properties. @@ -171,6 +177,7 @@ function validate(type: string, registryItem: Function|AnyDuringMigration) { /** * Unregisters the registry item with the given type and name. + * * @param type The type of the plugin. * (e.g. Field, Renderer) * @param name The plugin's name. (Ex. field_angle, geras) @@ -193,12 +200,13 @@ export function unregister(type: string|Type, name: string) { /** * Gets the registry item for the given name and type. This can be either a * class or an object. + * * @param type The type of the plugin. * (e.g. Field, Renderer) * @param name The plugin's name. (Ex. field_angle, geras) * @param opt_throwIfMissing Whether or not to throw an error if we are unable * to find the plugin. - * @return The class or object with the given name and type or null if none + * @returns The class or object with the given name and type or null if none * exists. */ function getItem( @@ -223,10 +231,11 @@ function getItem( /** * Returns whether or not the registry contains an item with the given type and * name. + * * @param type The type of the plugin. * (e.g. Field, Renderer) * @param name The plugin's name. (Ex. field_angle, geras) - * @return True if the registry has an item with the given type and name, false + * @returns True if the registry has an item with the given type and name, false * otherwise. * @alias Blockly.registry.hasItem */ @@ -242,12 +251,13 @@ export function hasItem(type: string|Type, name: string): boolean { /** * Gets the class for the given name and type. + * * @param type The type of the plugin. * (e.g. Field, Renderer) * @param name The plugin's name. (Ex. field_angle, geras) * @param opt_throwIfMissing Whether or not to throw an error if we are unable * to find the plugin. - * @return The class with the given name and type or null if none exists. + * @returns The class with the given name and type or null if none exists. * @alias Blockly.registry.getClass */ export function getClass( @@ -260,12 +270,13 @@ export function getClass( /** * Gets the object for the given name and type. + * * @param type The type of the plugin. * (e.g. Category) * @param name The plugin's name. (Ex. logic_category) * @param opt_throwIfMissing Whether or not to throw an error if we are unable * to find the object. - * @return The object with the given name and type or null if none exists. + * @returns The object with the given name and type or null if none exists. * @alias Blockly.registry.getObject */ export function getObject( @@ -275,12 +286,13 @@ export function getObject( /** * Returns a map of items registered with the given type. + * * @param type The type of the plugin. (e.g. Category) * @param opt_cased Whether or not to return a map with cased keys (rather than * caseless keys). False by default. * @param opt_throwIfMissing Whether or not to throw an error if we are unable * to find the object. False by default. - * @return A map of objects with the given type, or null if none exists. + * @returns A map of objects with the given type, or null if none exists. * @alias Blockly.registry.getAllItems */ export function getAllItems( @@ -313,11 +325,12 @@ export function getAllItems( /** * Gets the class from Blockly options for the given type. * This is used for plugins that override a built in feature. (e.g. Toolbox) + * * @param type The type of the plugin. * @param options The option object to check for the given plugin. * @param opt_throwIfMissing Whether or not to throw an error if we are unable * to find the plugin. - * @return The class for the plugin. + * @returns The class for the plugin. * @alias Blockly.registry.getClassFromOptions */ export function getClassFromOptions( diff --git a/core/rendered_connection.ts b/core/rendered_connection.ts index d33ba250e..1bc3eef71 100644 --- a/core/rendered_connection.ts +++ b/core/rendered_connection.ts @@ -6,6 +6,7 @@ /** * Components for creating connections between blocks. + * * @class */ import * as goog from '../closure/goog/goog.js'; @@ -42,6 +43,7 @@ const BUMP_RANDOMNESS = 10; /** * Class for a connection between blocks that may be rendered on screen. + * * @alias Blockly.RenderedConnection */ export class RenderedConnection extends Connection { @@ -86,6 +88,7 @@ export class RenderedConnection extends Connection { /** * Dispose of this connection. Remove it from the database (if it is * tracked) and call the super-function to deal with connected blocks. + * * @internal */ override dispose() { @@ -97,7 +100,8 @@ export class RenderedConnection extends Connection { /** * Get the source block for this connection. - * @return The source block. + * + * @returns The source block. */ override getSourceBlock(): BlockSvg { return super.getSourceBlock() as BlockSvg; @@ -105,7 +109,8 @@ export class RenderedConnection extends Connection { /** * Returns the block that this connection connects to. - * @return The connected block or null if none is connected. + * + * @returns The connected block or null if none is connected. */ override targetBlock(): BlockSvg|null { return super.targetBlock() as BlockSvg; @@ -114,8 +119,9 @@ export class RenderedConnection extends Connection { /** * Returns the distance between this connection and another connection in * workspace units. + * * @param otherConnection The other connection to measure the distance to. - * @return The distance between connections, in workspace units. + * @returns The distance between connections, in workspace units. */ distanceFrom(otherConnection: Connection): number { const xDiff = this.x - otherConnection.x; @@ -126,6 +132,7 @@ export class RenderedConnection extends Connection { /** * Move the block(s) belonging to the connection to a point where they don't * visually interfere with the specified connection. + * * @param staticConnection The connection to move away from. * @internal */ @@ -173,6 +180,7 @@ export class RenderedConnection extends Connection { /** * Change the connection's coordinates. + * * @param x New absolute x coordinate, in workspace coordinates. * @param y New absolute y coordinate, in workspace coordinates. */ @@ -190,6 +198,7 @@ export class RenderedConnection extends Connection { /** * Change the connection's coordinates. + * * @param dx Change to x coordinate, in workspace units. * @param dy Change to y coordinate, in workspace units. */ @@ -200,6 +209,7 @@ export class RenderedConnection extends Connection { /** * Move this connection to the location given by its offset within the block * and the location of the block's top left corner. + * * @param blockTL The location of the top left corner of the block, in * workspace coordinates. */ @@ -210,6 +220,7 @@ export class RenderedConnection extends Connection { /** * Set the offset of this connection relative to the top left of its block. + * * @param x The new relative x, in workspace units. * @param y The new relative y, in workspace units. */ @@ -220,7 +231,8 @@ export class RenderedConnection extends Connection { /** * Get the offset of this connection relative to the top left of its block. - * @return The offset of the connection. + * + * @returns The offset of the connection. * @internal */ getOffsetInBlock(): Coordinate { @@ -229,6 +241,7 @@ export class RenderedConnection extends Connection { /** * Move the blocks on either side of this connection right next to each other. + * * @internal */ tighten() { @@ -251,10 +264,11 @@ export class RenderedConnection extends Connection { /** * Find the closest compatible connection to this connection. * All parameters are in workspace units. + * * @param maxLimit The maximum radius to another connection. * @param dxy Offset between this connection's location in the database and * the current location (as a result of dragging). - * @return Contains two properties: 'connection' which is either another + * @returns Contains two properties: 'connection' which is either another * connection or null, and 'radius' which is the distance. */ closest(maxLimit: number, dxy: Coordinate): @@ -311,6 +325,7 @@ export class RenderedConnection extends Connection { /** * Set whether this connections is tracked in the database or not. + * * @param doTracking If true, start tracking. If false, stop tracking. * @internal */ @@ -342,6 +357,7 @@ export class RenderedConnection extends Connection { * collapsed. * * Also closes down-stream icons/bubbles. + * * @internal */ stopTrackingAll() { @@ -368,7 +384,8 @@ export class RenderedConnection extends Connection { * Start tracking this connection, as well as all down-stream connections on * any block attached to this connection. This happens when a block is * expanded. - * @return List of blocks to render. + * + * @returns List of blocks to render. */ startTrackingAll(): Block[] { this.setTracking(true); @@ -410,6 +427,7 @@ export class RenderedConnection extends Connection { * Behavior after a connection attempt fails. * Bumps this connection away from the other connection. Called when an * attempted connection fails. + * * @param otherConnection Connection that this connection failed to connect * to. * @internal @@ -430,6 +448,7 @@ export class RenderedConnection extends Connection { /** * Disconnect two blocks that are connected by this connection. + * * @param parentBlock The superior block. * @param childBlock The inferior block. */ @@ -472,9 +491,10 @@ export class RenderedConnection extends Connection { /** * Find all nearby compatible connections to this connection. * Type checking does not apply, since this function is used for bumping. + * * @param maxLimit The maximum radius to another connection, in workspace * units. - * @return List of connections. + * @returns List of connections. * @internal */ override neighbours(maxLimit: number): Connection[] { @@ -484,6 +504,7 @@ export class RenderedConnection extends Connection { /** * Connect two connections together. This is the connection on the superior * block. Rerender blocks as needed. + * * @param childConnection Connection on inferior block. */ protected override connect_(childConnection: Connection) { diff --git a/core/renderers/common/block_rendering.ts b/core/renderers/common/block_rendering.ts index 6561c2c65..22337e3ca 100644 --- a/core/renderers/common/block_rendering.ts +++ b/core/renderers/common/block_rendering.ts @@ -6,6 +6,7 @@ /** * Namespace for block rendering functionality. + * * @namespace Blockly.blockRendering */ import * as goog from '../../../closure/goog/goog.js'; @@ -50,7 +51,8 @@ import {Renderer} from './renderer.js'; /** * Returns whether the debugger is turned on. - * @return Whether the debugger is turned on. + * + * @returns Whether the debugger is turned on. * @alias Blockly.blockRendering.isDebuggerEnabled * @deprecated * @internal @@ -65,6 +67,7 @@ export function isDebuggerEnabled(): boolean { /** * Registers a new renderer. + * * @param name The name of the renderer. * @param rendererClass The new renderer class to register. * @throws {Error} if a renderer with the same name has already been registered. @@ -75,6 +78,7 @@ export function register(name: string, rendererClass: Function) { /** * Unregisters the renderer registered with the given name. + * * @param name The name of the renderer. * @alias Blockly.blockRendering.unregister */ @@ -84,6 +88,7 @@ export function unregister(name: string) { /** * Turn on the blocks debugger. + * * @alias Blockly.blockRendering.startDebugger * @deprecated * @internal @@ -98,6 +103,7 @@ export function startDebugger() { /** * Turn off the blocks debugger. + * * @alias Blockly.blockRendering.stopDebugger * @deprecated * @internal @@ -112,10 +118,11 @@ export function stopDebugger() { /** * Initialize anything needed for rendering (constants, etc). + * * @param name Name of the renderer to initialize. * @param theme The workspace theme object. * @param opt_rendererOverrides Rendering constant overrides. - * @return The new instance of a renderer. + * @returns The new instance of a renderer. * Already initialized. * @alias Blockly.blockRendering.init * @internal diff --git a/core/renderers/common/constants.ts b/core/renderers/common/constants.ts index 984844992..f31c07f99 100644 --- a/core/renderers/common/constants.ts +++ b/core/renderers/common/constants.ts @@ -6,6 +6,7 @@ /** * An object that provides constants for rendering blocks. + * * @class */ import * as goog from '../../../closure/goog/goog.js'; @@ -108,6 +109,7 @@ export type Shape = BaseShape|DynamicShape; /** * An object that provides constants for rendering blocks. + * * @alias Blockly.blockRendering.ConstantProvider */ export class ConstantProvider { @@ -241,6 +243,7 @@ export class ConstantProvider { /** * The backing colour of a field's border rect. + * * @internal */ FIELD_BORDER_RECT_COLOUR = '#fff'; @@ -294,6 +297,7 @@ export class ConstantProvider { /** * The ID of the emboss filter, or the empty string if no filter is set. + * * @internal */ embossFilterId = ''; @@ -305,6 +309,7 @@ export class ConstantProvider { /** * The ID of the disabled pattern, or the empty string if no pattern is set. + * * @internal */ disabledPatternId = ''; @@ -335,48 +340,56 @@ export class ConstantProvider { /** * Cursor colour. + * * @internal */ CURSOR_COLOUR = '#cc0a0a'; /** * Immovable marker colour. + * * @internal */ MARKER_COLOUR = '#4286f4'; /** * Width of the horizontal cursor. + * * @internal */ CURSOR_WS_WIDTH = 100; /** * Height of the horizontal cursor. + * * @internal */ WS_CURSOR_HEIGHT = 5; /** * Padding around a stack. + * * @internal */ CURSOR_STACK_PADDING = 10; /** * Padding around a block. + * * @internal */ CURSOR_BLOCK_PADDING = 2; /** * Stroke of the cursor. + * * @internal */ CURSOR_STROKE_WIDTH = 4; /** * Whether text input and colour fields fill up the entire source block. + * * @internal */ FULL_BLOCK_FIELDS = false; @@ -384,12 +397,14 @@ export class ConstantProvider { /** * The main colour of insertion markers, in hex. The block is rendered a * transparent grey by changing the fill opacity in CSS. + * * @internal */ INSERTION_MARKER_COLOUR = '#000000'; /** * The insertion marker opacity. + * * @internal */ INSERTION_MARKER_OPACITY = 0.2; @@ -489,6 +504,7 @@ export class ConstantProvider { /** * A random identifier used to ensure a unique ID is used for each * filter/pattern for the case of multiple Blockly instances on a page. + * * @internal */ this.randomIdentifier = String(Math.random()).substring(2); @@ -496,6 +512,7 @@ export class ConstantProvider { /** * Initialize shape objects based on the constants set in the constructor. + * * @internal */ init() { @@ -529,6 +546,7 @@ export class ConstantProvider { /** * Refresh constants properties that depend on the theme. + * * @param theme The current workspace theme. * @internal */ @@ -546,6 +564,7 @@ export class ConstantProvider { /** * Sets dynamic properties that depend on other values or theme properties. + * * @param theme The current workspace theme. */ protected setDynamicProperties_(theme: Theme) { @@ -558,6 +577,7 @@ export class ConstantProvider { /** * Set constants related to fonts. + * * @param theme The current workspace theme. */ protected setFontConstants_(theme: Theme) { @@ -583,6 +603,7 @@ export class ConstantProvider { /** * Set constants from a theme's component styles. + * * @param theme The current workspace theme. */ protected setComponentConstants_(theme: Theme) { @@ -601,8 +622,9 @@ export class ConstantProvider { /** * Get or create a block style based on a single colour value. Generate a * name for the style based on the colour. + * * @param colour #RRGGBB colour string. - * @return An object containing the style and an autogenerated name for that + * @returns An object containing the style and an autogenerated name for that * style. * @internal */ @@ -616,8 +638,9 @@ export class ConstantProvider { /** * Gets the BlockStyle for the given block style name. + * * @param blockStyleName The name of the block style. - * @return The named block style, or a default style if no style with the + * @returns The named block style, or a default style if no style with the * given name was found. */ getBlockStyle(blockStyleName: string|null): BlockStyle { @@ -629,8 +652,9 @@ export class ConstantProvider { /** * Create a block style object based on the given colour. + * * @param colour #RRGGBB colour string. - * @return A populated block style based on the given colour. + * @returns A populated block style based on the given colour. */ protected createBlockStyle_(colour: string): BlockStyle { return this.validatedBlockStyle_({'colourPrimary': colour}); @@ -639,8 +663,13 @@ export class ConstantProvider { /** * Get a full block style object based on the input style object. Populate * any missing values. + * * @param blockStyle A full or partial block style object. - * @return A full block style object, with all required properties populated. + * @param blockStyle.colourPrimary + * @param blockStyle.colourSecondary + * @param blockStyle.colourTertiary + * @param blockStyle.hat + * @returns A full block style object, with all required properties populated. */ protected validatedBlockStyle_(blockStyle: { colourPrimary: string, @@ -670,8 +699,9 @@ export class ConstantProvider { /** * Generate a secondary colour from the passed in primary colour. + * * @param inputColour Primary colour. - * @return The generated secondary colour. + * @returns The generated secondary colour. */ protected generateSecondaryColour_(inputColour: string): string { return colour.blend('#fff', inputColour, 0.6) || inputColour; @@ -679,8 +709,9 @@ export class ConstantProvider { /** * Generate a tertiary colour from the passed in primary colour. + * * @param inputColour Primary colour. - * @return The generated tertiary colour. + * @returns The generated tertiary colour. */ protected generateTertiaryColour_(inputColour: string): string { return colour.blend('#fff', inputColour, 0.3) || inputColour; @@ -689,6 +720,7 @@ export class ConstantProvider { /** * Dispose of this constants provider. * Delete all DOM elements that this provider created. + * * @internal */ dispose() { @@ -707,7 +739,7 @@ export class ConstantProvider { } /** - * @return An object containing sizing and path information about collapsed + * @returns An object containing sizing and path information about collapsed * block indicators. * @internal */ @@ -724,7 +756,7 @@ export class ConstantProvider { } /** - * @return An object containing sizing and path information about start hats. + * @returns An object containing sizing and path information about start hats. * @internal */ makeStartHat(): StartHat { @@ -740,7 +772,7 @@ export class ConstantProvider { } /** - * @return An object containing sizing and path information about puzzle tabs. + * @returns An object containing sizing and path information about puzzle tabs. * @internal */ makePuzzleTab(): PuzzleTab { @@ -753,9 +785,10 @@ export class ConstantProvider { * versions of the paths are the same, but the Y sign flips. Forward and * back are the signs to use to move the cursor in the direction that the * path is being drawn. + * * @param up True if the path should be drawn from bottom to top, false * otherwise. - * @return A path fragment describing a puzzle tab. + * @returns A path fragment describing a puzzle tab. */ function makeMainPath(up: boolean): string { const forward = up ? -1 : 1; @@ -796,7 +829,7 @@ export class ConstantProvider { } /** - * @return An object containing sizing and path information about notches. + * @returns An object containing sizing and path information about notches. * @internal */ makeNotch(): Notch { @@ -807,9 +840,10 @@ export class ConstantProvider { /** * Make the main path for the notch. + * * @param dir Direction multiplier to apply to horizontal offsets along the * path. Either 1 or -1. - * @return A path fragment describing a notch. + * @returns A path fragment describing a notch. */ function makeMainPath(dir: number): string { return svgPaths.line([ @@ -831,7 +865,7 @@ export class ConstantProvider { } /** - * @return An object containing sizing and path information about inside + * @returns An object containing sizing and path information about inside * corners. * @internal */ @@ -853,7 +887,7 @@ export class ConstantProvider { } /** - * @return An object containing sizing and path information about outside + * @returns An object containing sizing and path information about outside * corners. * @internal */ @@ -887,8 +921,9 @@ export class ConstantProvider { /** * Get an object with connection shape and sizing information based on the * type of the connection. + * * @param connection The connection to find a shape object for - * @return The shape object for the connection. + * @returns The shape object for the connection. * @internal */ shapeFor(connection: RenderedConnection): Shape { @@ -906,6 +941,7 @@ export class ConstantProvider { /** * Create any DOM elements that this renderer needs (filters, patterns, etc). + * * @param svg The root of the workspace's SVG. * @param tagName The name to use for the CSS style tag. * @param selector The CSS selector to use. @@ -1056,6 +1092,7 @@ export class ConstantProvider { /** * Inject renderer specific CSS into the page. + * * @param tagName The name of the style tag to use. * @param selector The CSS selector to use. */ @@ -1080,8 +1117,9 @@ export class ConstantProvider { /** * Get any renderer specific CSS to inject when the renderer is initialized. + * * @param selector CSS selector to use. - * @return Array of CSS strings. + * @returns Array of CSS strings. */ protected getCSS_(selector: string): string[] { return [ diff --git a/core/renderers/common/debug.ts b/core/renderers/common/debug.ts index 2e6bdf005..a0c2f98ab 100644 --- a/core/renderers/common/debug.ts +++ b/core/renderers/common/debug.ts @@ -6,6 +6,7 @@ /** * Block rendering debugging functionality. + * * @namespace Blockly.blockRendering.debug */ import * as goog from '../../../closure/goog/goog.js'; @@ -18,7 +19,8 @@ import * as deprecation from '../../utils/deprecation.js'; let useDebugger = false; /** * Returns whether the debugger is turned on. - * @return Whether the debugger is turned on. + * + * @returns Whether the debugger is turned on. * @alias Blockly.blockRendering.debug.isDebuggerEnabled * @internal */ @@ -28,6 +30,7 @@ export function isDebuggerEnabled(): boolean { /** * Turn on the blocks debugger. + * * @alias Blockly.blockRendering.debug.startDebugger * @deprecated March 2022. Use the rendering debugger in @blockly/dev-tools. * See https://www.npmjs.com/package/@blockly/dev-tools for more information. @@ -43,6 +46,7 @@ export function startDebugger() { /** * Turn off the blocks debugger. + * * @alias Blockly.blockRendering.debug.stopDebugger * @deprecated March 2022. Use the rendering debugger in @blockly/dev-tools. * See https://www.npmjs.com/package/@blockly/dev-tools for more information. diff --git a/core/renderers/common/debugger.ts b/core/renderers/common/debugger.ts index 971e6e638..9b49a46e6 100644 --- a/core/renderers/common/debugger.ts +++ b/core/renderers/common/debugger.ts @@ -6,6 +6,7 @@ /** * Methods for rendering debug graphics. + * * @class */ import * as goog from '../../../closure/goog/goog.js'; @@ -31,12 +32,14 @@ import type {RenderInfo} from './info.js'; /** * An object that renders rectangles and dots for debugging rendering code. + * * @alias Blockly.blockRendering.Debug */ export class Debug { /** * Configuration object containing booleans to enable and disable debug * rendering of specific rendering components. + * * @struct */ static config = { @@ -71,6 +74,7 @@ export class Debug { /** * Remove all elements the this object created on the last pass. + * * @internal */ clearElems() { @@ -84,6 +88,7 @@ export class Debug { /** * Draw a debug rectangle for a spacer (empty) row. + * * @param row The row to render. * @param cursorY The y position of the top of the row. * @param isRtl Whether the block is rendered RTL. @@ -117,6 +122,7 @@ export class Debug { /** * Draw a debug rectangle for a horizontal spacer. + * * @param elem The spacer to render. * @param rowHeight The height of the container row. * @param isRtl Whether the block is rendered RTL. @@ -151,6 +157,7 @@ export class Debug { /** * Draw a debug rectangle for an in-row element. + * * @param elem The element to render. * @param isRtl Whether the block is rendered RTL. * @internal @@ -203,6 +210,7 @@ export class Debug { * Draw a circle at the location of the given connection. Inputs and outputs * share the same colours, as do previous and next. When positioned correctly * a connected pair will look like a bullseye. + * * @param conn The connection to circle. * @suppress {visibility} Suppress visibility of conn.offsetInBlock_ since * this is a debug module. @@ -251,6 +259,7 @@ export class Debug { /** * Draw a debug rectangle for a non-empty row. + * * @param row The non-empty row to render. * @param cursorY The y position of the top of the row. * @param isRtl Whether the block is rendered RTL. @@ -298,6 +307,7 @@ export class Debug { /** * Draw debug rectangles for a non-empty row and all of its subcomponents. + * * @param row The non-empty row to render. * @param cursorY The y position of the top of the row. * @param isRtl Whether the block is rendered RTL. @@ -321,6 +331,7 @@ export class Debug { /** * Draw a debug rectangle around the entire block. + * * @param info Rendering information about the block to debug. * @internal */ @@ -366,6 +377,7 @@ export class Debug { /** * Do all of the work to draw debug information for the whole block. + * * @param block The block to draw debug information for. * @param info Rendering information about the block to debug. * @internal @@ -413,6 +425,7 @@ export class Debug { /** * Show a debug filter to highlight that a block has been rendered. + * * @param svgPath The block's SVG path. * @internal */ diff --git a/core/renderers/common/drawer.ts b/core/renderers/common/drawer.ts index 48eb502b5..83074dfa3 100644 --- a/core/renderers/common/drawer.ts +++ b/core/renderers/common/drawer.ts @@ -6,6 +6,7 @@ /** * Methods for graphically rendering a block as SVG. + * * @class */ import * as goog from '../../../closure/goog/goog.js'; @@ -29,6 +30,7 @@ import type {RenderInfo} from './info.js'; /** * An object that draws a block based on the given rendering information. + * * @alias Blockly.blockRendering.Drawer */ export class Drawer { @@ -62,6 +64,7 @@ export class Drawer { * joined with spaces and set directly on the block. This guarantees that * the steps are separated by spaces for improved readability, but isn't * required. + * * @internal */ draw() { @@ -151,6 +154,7 @@ export class Drawer { /** * Add steps for the jagged edge of a row on a collapsed block. + * * @param row The row to draw the side of. */ protected drawJaggedEdge_(row: Row) { @@ -162,6 +166,7 @@ export class Drawer { /** * Add steps for an external value input, rendered as a notch in the side * of the block. + * * @param row The row that this input belongs to. */ protected drawValueInput_(row: Row) { @@ -185,6 +190,7 @@ export class Drawer { /** * Add steps for a statement input. + * * @param row The row that this input belongs to. */ protected drawStatementInput_(row: Row) { @@ -210,6 +216,7 @@ export class Drawer { /** * Add steps for the right side of a row that does not have value or * statement input connections. + * * @param row The row to draw the side of. */ protected drawRightSideRow_(row: Row) { @@ -289,6 +296,7 @@ export class Drawer { /** * Push a field or icon's new position to its SVG root. + * * @param fieldInfo The rendering information for the field or icon. */ protected layoutField_(fieldInfo: Icon|Field) { @@ -336,6 +344,7 @@ export class Drawer { /** * Add steps for an inline input. + * * @param input The information about the input to render. */ protected drawInlineInput_(input: InlineInput) { @@ -361,6 +370,7 @@ export class Drawer { * Position the connection on an inline value input, taking into account * RTL and the small gap between the parent block and child block which lets * the parent block's dark path show through. + * * @param input The information about the input that the connection is on. */ protected positionInlineInputConnection_(input: InlineInput) { @@ -381,6 +391,7 @@ export class Drawer { * Position the connection on a statement input, taking into account * RTL and the small gap between the parent block and child block which lets * the parent block's dark path show through. + * * @param row The row that the connection is on. */ protected positionStatementInputConnection_(row: Row) { @@ -398,6 +409,7 @@ export class Drawer { * Position the connection on an external value input, taking into account * RTL and the small gap between the parent block and child block which lets * the parent block's dark path show through. + * * @param row The row that the connection is on. */ protected positionExternalValueConnection_(row: Row) { diff --git a/core/renderers/common/i_path_object.ts b/core/renderers/common/i_path_object.ts index 7c89039d9..a668c6a2a 100644 --- a/core/renderers/common/i_path_object.ts +++ b/core/renderers/common/i_path_object.ts @@ -7,6 +7,7 @@ /** * The interface for an object that owns a block's rendering SVG * elements. + * * @namespace Blockly.blockRendering.IPathObject */ import * as goog from '../../../closure/goog/goog.js'; @@ -29,6 +30,7 @@ import type {ConstantProvider} from './constants.js'; /** * An interface for a block's path object. + * * @param _root The root SVG element. * @param _constants The renderer's constants. * @alias Blockly.blockRendering.IPathObject @@ -57,6 +59,7 @@ export interface IPathObject { /** * Set the path generated by the renderer onto the respective SVG element. + * * @param pathString The path. * @internal */ @@ -65,6 +68,7 @@ export interface IPathObject { /** * Apply the stored colours to the block's path, taking into account whether * the paths belong to a shadow block. + * * @param block The source block. * @internal */ @@ -72,6 +76,7 @@ export interface IPathObject { /** * Update the style. + * * @param blockStyle The block style to use. * @internal */ @@ -79,12 +84,14 @@ export interface IPathObject { /** * Flip the SVG paths in RTL. + * * @internal */ flipRTL: () => void; /** * Add the cursor SVG to this block's SVG group. + * * @param cursorSvg The SVG root of the cursor to be added to the block SVG * group. * @internal @@ -93,6 +100,7 @@ export interface IPathObject { /** * Add the marker SVG to this block's SVG group. + * * @param markerSvg The SVG root of the marker to be added to the block SVG * group. * @internal @@ -102,6 +110,7 @@ export interface IPathObject { /** * Set whether the block shows a highlight or not. Block highlighting is * often used to visually mark blocks currently being executed. + * * @param highlighted True if highlighted. * @internal */ @@ -109,6 +118,7 @@ export interface IPathObject { /** * Add or remove styling showing that a block is selected. + * * @param enable True if selection is enabled, false otherwise. * @internal */ @@ -116,6 +126,7 @@ export interface IPathObject { /** * Add or remove styling showing that a block is dragged over a delete area. + * * @param enable True if the block is being dragged over a delete area, false * otherwise. * @internal @@ -124,6 +135,7 @@ export interface IPathObject { /** * Add or remove styling showing that a block is an insertion marker. + * * @param enable True if the block is an insertion marker, false otherwise. * @internal */ @@ -131,6 +143,7 @@ export interface IPathObject { /** * Add or remove styling showing that a block is movable. + * * @param enable True if the block is movable, false otherwise. * @internal */ @@ -140,6 +153,7 @@ export interface IPathObject { * Add or remove styling that shows that if the dragging block is dropped, * this block will be replaced. If a shadow block, it will disappear. * Otherwise it will bump. + * * @param enable True if styling should be added. * @internal */ @@ -148,6 +162,7 @@ export interface IPathObject { /** * Add or remove styling that shows that if the dragging block is dropped, * this block will be connected to the input. + * * @param conn The connection on the input to highlight. * @param enable True if styling should be added. * @internal diff --git a/core/renderers/common/info.ts b/core/renderers/common/info.ts index 170e970df..96774df10 100644 --- a/core/renderers/common/info.ts +++ b/core/renderers/common/info.ts @@ -6,6 +6,7 @@ /** * Methods for graphically rendering a block as SVG. + * * @class */ import * as goog from '../../../closure/goog/goog.js'; @@ -46,6 +47,7 @@ import type {Renderer} from './renderer.js'; * This measure pass does not propagate changes to the block (although fields * may choose to rerender when getSize() is called). However, calling it * repeatedly may be expensive. + * * @alias Blockly.blockRendering.RenderInfo */ export class RenderInfo { @@ -145,7 +147,8 @@ export class RenderInfo { /** * Get the block renderer in use. - * @return The block renderer in use. + * + * @returns The block renderer in use. * @internal */ getRenderer(): Renderer { @@ -159,6 +162,7 @@ export class RenderInfo { * This measure pass does not propagate changes to the block (although fields * may choose to rerender when getSize() is called). However, calling it * repeatedly may be expensive. + * * @internal */ measure() { @@ -227,6 +231,7 @@ export class RenderInfo { /** * Create all non-spacer elements that belong on the top row. + * * @internal */ populateTopRow_() { @@ -271,6 +276,7 @@ export class RenderInfo { /** * Create all non-spacer elements that belong on the bottom row. + * * @internal */ populateBottomRow_() { @@ -315,6 +321,7 @@ export class RenderInfo { /** * Add an input element to the active row, if needed, and record the type of * the input on the row. + * * @param input The input to record information about. * @param activeRow The row that is currently being populated. */ @@ -346,9 +353,10 @@ export class RenderInfo { /** * Decide whether to start a new row between the two Blockly.Inputs. + * * @param input The first input to consider * @param lastInput The input that follows. - * @return True if the next input should be rendered on a new row. + * @returns True if the next input should be rendered on a new row. */ protected shouldStartNewRow_(input: Input, lastInput: Input): boolean { // If this is the first input, just add to the existing row. @@ -401,9 +409,10 @@ export class RenderInfo { * Calculate the width of a spacer element in a row based on the previous and * next elements in that row. For instance, extra padding is added between * two editable fields. + * * @param prev The element before the spacer. * @param next The element after the spacer. - * @return The size of the spacing between the two elements. + * @returns The size of the spacing between the two elements. */ protected getInRowSpacing_(prev: Measurable|null, next: Measurable|null): number { @@ -509,8 +518,9 @@ export class RenderInfo { /** * Calculate the desired width of an input row. + * * @param _row The input row. - * @return The desired width of the input row. + * @returns The desired width of the input row. */ protected getDesiredRowWidth_(_row: Row): number { return this.width - this.startX; @@ -520,6 +530,7 @@ export class RenderInfo { * Modify the given row to add the given amount of padding around its fields. * The exact location of the padding is based on the alignment property of the * last input in the field. + * * @param row The row to add padding to. * @param missingSpace How much padding to add. */ @@ -551,6 +562,7 @@ export class RenderInfo { /** * Align the elements of a statement row based on computed bounds. * Unlike other types of rows, statement rows add space in multiple places. + * * @param row The statement row to resize. */ protected alignStatementRow_(row: InputRow) { @@ -588,9 +600,10 @@ export class RenderInfo { /** * Create a spacer row to go between prev and next, and set its size. + * * @param prev The previous row. * @param next The next row. - * @return The newly created spacer row. + * @returns The newly created spacer row. */ protected makeSpacerRow_(prev: Row, next: Row): SpacerRow { const height = this.getSpacerRowHeight_(prev, next); @@ -607,9 +620,10 @@ export class RenderInfo { /** * Calculate the width of a spacer row. + * * @param _prev The row before the spacer. * @param _next The row after the spacer. - * @return The desired width of the spacer row between these two rows. + * @returns The desired width of the spacer row between these two rows. */ protected getSpacerRowWidth_(_prev: Row, _next: Row): number { return this.width - this.startX; @@ -617,9 +631,10 @@ export class RenderInfo { /** * Calculate the height of a spacer row. + * * @param _prev The row before the spacer. * @param _next The row after the spacer. - * @return The desired height of the spacer row between these two rows. + * @returns The desired height of the spacer row between these two rows. */ protected getSpacerRowHeight_(_prev: Row, _next: Row): number { return this.constants_.MEDIUM_PADDING; @@ -630,9 +645,10 @@ export class RenderInfo { * This base implementation puts the centerline at the middle of the row * vertically, with no special cases. You will likely need extra logic to * handle (at minimum) top and bottom rows. + * * @param row The row containing the element. * @param elem The element to place. - * @return The desired centerline of the given element, as an offset from the + * @returns The desired centerline of the given element, as an offset from the * top left of the block. */ protected getElemCenterline_(row: Row, elem: Measurable): number { @@ -663,6 +679,7 @@ export class RenderInfo { /** * Record final position information on elements on the given row, for use in * drawing. At minimum this records xPos and centerline on each element. + * * @param row The row containing the elements. */ protected recordElemPositions_(row: Row) { diff --git a/core/renderers/common/marker_svg.ts b/core/renderers/common/marker_svg.ts index a1f2996dc..8710fc69a 100644 --- a/core/renderers/common/marker_svg.ts +++ b/core/renderers/common/marker_svg.ts @@ -6,6 +6,7 @@ /** * Methods for graphically rendering a marker as SVG. + * * @class */ import * as goog from '../../../closure/goog/goog.js'; @@ -45,6 +46,7 @@ const HEIGHT_MULTIPLIER = 3 / 4; /** * Class for a marker. + * * @alias Blockly.blockRendering.MarkerSvg */ export class MarkerSvg { @@ -91,7 +93,8 @@ export class MarkerSvg { /** * Return the root node of the SVG or null if none exists. - * @return The root SVG node. + * + * @returns The root SVG node. */ getSvgRoot(): SVGElement { // AnyDuringMigration because: Type 'SVGGElement | null' is not assignable @@ -101,7 +104,8 @@ export class MarkerSvg { /** * Get the marker. - * @return The marker to draw for. + * + * @returns The marker to draw for. */ getMarker(): Marker { return this.marker; @@ -110,7 +114,8 @@ export class MarkerSvg { /** * True if the marker should be drawn as a cursor, false otherwise. * A cursor is drawn as a flashing line. A marker is drawn as a solid line. - * @return True if the marker is a cursor, false otherwise. + * + * @returns True if the marker is a cursor, false otherwise. */ isCursor(): boolean { return this.marker.type === 'cursor'; @@ -118,7 +123,8 @@ export class MarkerSvg { /** * Create the DOM element for the marker. - * @return The marker controls SVG group. + * + * @returns The marker controls SVG group. * @internal */ createDom(): SVGElement { @@ -132,6 +138,7 @@ export class MarkerSvg { /** * Attaches the SVG root of the marker to the SVG group of the parent. + * * @param newParent The workspace, field, or block that the marker SVG element * should be attached to. */ @@ -152,6 +159,7 @@ export class MarkerSvg { /** * Update the marker. + * * @param oldNode The previous node the marker was on or null. * @param curNode The node that we want to draw the marker for. */ @@ -181,6 +189,7 @@ export class MarkerSvg { /** * Update the marker's visible state based on the type of curNode.. + * * @param curNode The node that we want to draw the marker for. */ protected showAtLocation_(curNode: ASTNode) { @@ -212,6 +221,7 @@ export class MarkerSvg { /** * Show the marker as a combination of the previous connection and block, * the output connection and block, or just the block. + * * @param curNode The node to draw the marker for. */ private showWithBlockPrevOutput_(curNode: ASTNode) { @@ -240,6 +250,7 @@ export class MarkerSvg { /** * Position and display the marker for a block. + * * @param curNode The node to draw the marker for. */ protected showWithBlock_(curNode: ASTNode) { @@ -248,6 +259,7 @@ export class MarkerSvg { /** * Position and display the marker for a previous connection. + * * @param curNode The node to draw the marker for. */ protected showWithPrevious_(curNode: ASTNode) { @@ -256,6 +268,7 @@ export class MarkerSvg { /** * Position and display the marker for an output connection. + * * @param curNode The node to draw the marker for. */ protected showWithOutput_(curNode: ASTNode) { @@ -265,6 +278,7 @@ export class MarkerSvg { /** * Position and display the marker for a workspace coordinate. * This is a horizontal line. + * * @param curNode The node to draw the marker for. */ protected showWithCoordinates_(curNode: ASTNode) { @@ -284,6 +298,7 @@ export class MarkerSvg { /** * Position and display the marker for a field. * This is a box around the field. + * * @param curNode The node to draw the marker for. */ protected showWithField_(curNode: ASTNode) { @@ -299,6 +314,7 @@ export class MarkerSvg { /** * Position and display the marker for an input. * This is a puzzle piece. + * * @param curNode The node to draw the marker for. */ protected showWithInput_(curNode: ASTNode) { @@ -313,6 +329,7 @@ export class MarkerSvg { /** * Position and display the marker for a next connection. * This is a horizontal line. + * * @param curNode The node to draw the marker for. */ protected showWithNext_(curNode: ASTNode) { @@ -332,6 +349,7 @@ export class MarkerSvg { /** * Position and display the marker for a stack. * This is a box with extra padding around the entire stack of blocks. + * * @param curNode The node to draw the marker for. */ protected showWithStack_(curNode: ASTNode) { @@ -376,6 +394,7 @@ export class MarkerSvg { /** * Position the marker for a block. * Displays an outline of the top half of a rectangle around a block. + * * @param width The width of the block. * @param markerOffset The extra padding for around the block. * @param markerHeight The height of the marker. @@ -398,6 +417,7 @@ export class MarkerSvg { /** * Position the marker for an input connection. * Displays a filled in puzzle piece. + * * @param connection The connection to position marker around. */ protected positionInput_(connection: RenderedConnection) { @@ -418,6 +438,7 @@ export class MarkerSvg { /** * Move and show the marker at the specified coordinate in workspace units. * Displays a horizontal line. + * * @param x The new x, in workspace units. * @param y The new y, in workspace units. * @param width The new width, in workspace units. @@ -438,6 +459,7 @@ export class MarkerSvg { /** * Position the marker for an output connection. * Displays a puzzle outline and the top and bottom path. + * * @param width The width of the block. * @param height The height of the block. * @param connectionShape The shape object for the connection. @@ -464,6 +486,7 @@ export class MarkerSvg { * Position the marker for a previous connection. * Displays a half rectangle with a notch in the top to represent the previous * connection. + * * @param width The width of the block. * @param markerOffset The offset of the marker from around the block. * @param markerHeight The height of the marker. @@ -492,6 +515,7 @@ export class MarkerSvg { /** * Move and show the marker at the specified coordinate in workspace units. * Displays a filled in rectangle. + * * @param x The new x, in workspace units. * @param y The new y, in workspace units. * @param width The new width, in workspace units. @@ -515,6 +539,7 @@ export class MarkerSvg { /** * Flip the SVG paths in RTL. + * * @param markerSvg The marker that we want to flip. */ private flipRtl_(markerSvg: SVGElement) { @@ -531,6 +556,7 @@ export class MarkerSvg { /** * Fire event for the marker or marker. + * * @param oldNode The old node the marker used to be on. * @param curNode The new node the marker is currently on. */ @@ -543,7 +569,8 @@ export class MarkerSvg { /** * Get the properties to make a marker blink. - * @return The object holding attributes to make the marker blink. + * + * @returns The object holding attributes to make the marker blink. */ protected getBlinkProperties_(): AnyDuringMigration { return { @@ -557,7 +584,8 @@ export class MarkerSvg { /** * Create the marker SVG. - * @return The SVG node created. + * + * @returns The SVG node created. */ protected createDomInternal_(): Element { /* This markup will be generated and added to the .svgGroup_: @@ -651,6 +679,7 @@ export class MarkerSvg { /** * Apply the marker's colour. + * * @param _curNode The node that we want to draw the marker for. */ protected applyColour_(_curNode: ASTNode) { diff --git a/core/renderers/common/path_object.ts b/core/renderers/common/path_object.ts index da6b0d05a..43cc7125f 100644 --- a/core/renderers/common/path_object.ts +++ b/core/renderers/common/path_object.ts @@ -6,6 +6,7 @@ /** * An object that owns a block's rendering SVG elements. + * * @class */ import * as goog from '../../../closure/goog/goog.js'; @@ -28,6 +29,7 @@ import type {IPathObject} from './i_path_object.js'; /** * An object that handles creating and setting each of the SVG elements * used by the renderer. + * * @alias Blockly.blockRendering.PathObject */ export class PathObject implements IPathObject { @@ -38,6 +40,7 @@ export class PathObject implements IPathObject { /** * Holds the cursors svg element when the cursor is attached to the block. * This is null if there is no cursor on the block. + * * @internal */ // AnyDuringMigration because: Type 'null' is not assignable to type @@ -47,6 +50,7 @@ export class PathObject implements IPathObject { /** * Holds the markers svg element when the marker is attached to the block. * This is null if there is no marker on the block. + * * @internal */ // AnyDuringMigration because: Type 'null' is not assignable to type @@ -77,6 +81,7 @@ export class PathObject implements IPathObject { /** * Set the path generated by the renderer onto the respective SVG element. + * * @param pathString The path. * @internal */ @@ -86,6 +91,7 @@ export class PathObject implements IPathObject { /** * Flip the SVG paths in RTL. + * * @internal */ flipRTL() { @@ -95,6 +101,7 @@ export class PathObject implements IPathObject { /** * Add the cursor SVG to this block's SVG group. + * * @param cursorSvg The SVG root of the cursor to be added to the block SVG * group. * @internal @@ -113,6 +120,7 @@ export class PathObject implements IPathObject { /** * Add the marker SVG to this block's SVG group. + * * @param markerSvg The SVG root of the marker to be added to the block SVG * group. * @internal @@ -136,6 +144,7 @@ export class PathObject implements IPathObject { /** * Apply the stored colours to the block's path, taking into account whether * the paths belong to a shadow block. + * * @param block The source block. * @internal */ @@ -149,6 +158,7 @@ export class PathObject implements IPathObject { /** * Set the style. + * * @param blockStyle The block style to use. * @internal */ @@ -158,6 +168,7 @@ export class PathObject implements IPathObject { /** * Add or remove the given CSS class on the path object's root SVG element. + * * @param className The name of the class to add or remove * @param add True if the class should be added. False if it should be * removed. @@ -173,6 +184,7 @@ export class PathObject implements IPathObject { /** * Set whether the block shows a highlight or not. Block highlighting is * often used to visually mark blocks currently being executed. + * * @param enable True if highlighted. * @internal */ @@ -187,6 +199,7 @@ export class PathObject implements IPathObject { /** * Updates the look of the block to reflect a shadow state. + * * @param shadow True if the block is a shadow block. */ protected updateShadow_(shadow: boolean) { @@ -198,6 +211,7 @@ export class PathObject implements IPathObject { /** * Updates the look of the block to reflect a disabled state. + * * @param disabled True if disabled. */ protected updateDisabled_(disabled: boolean) { @@ -210,6 +224,7 @@ export class PathObject implements IPathObject { /** * Add or remove styling showing that a block is selected. + * * @param enable True if selection is enabled, false otherwise. * @internal */ @@ -219,6 +234,7 @@ export class PathObject implements IPathObject { /** * Add or remove styling showing that a block is dragged over a delete area. + * * @param enable True if the block is being dragged over a delete area, false * otherwise. * @internal @@ -229,6 +245,7 @@ export class PathObject implements IPathObject { /** * Add or remove styling showing that a block is an insertion marker. + * * @param enable True if the block is an insertion marker, false otherwise. * @internal */ @@ -238,6 +255,7 @@ export class PathObject implements IPathObject { /** * Add or remove styling showing that a block is movable. + * * @param enable True if the block is movable, false otherwise. * @internal */ @@ -249,6 +267,7 @@ export class PathObject implements IPathObject { * Add or remove styling that shows that if the dragging block is dropped, * this block will be replaced. If a shadow block, it will disappear. * Otherwise it will bump. + * * @param enable True if styling should be added. * @internal */ @@ -259,6 +278,7 @@ export class PathObject implements IPathObject { /** * Add or remove styling that shows that if the dragging block is dropped, * this block will be connected to the input. + * * @param _conn The connection on the input to highlight. * @param _enable True if styling should be added. * @internal diff --git a/core/renderers/common/renderer.ts b/core/renderers/common/renderer.ts index a166b4cb1..59e970458 100644 --- a/core/renderers/common/renderer.ts +++ b/core/renderers/common/renderer.ts @@ -6,6 +6,7 @@ /** * Base renderer. + * * @class */ import * as goog from '../../../closure/goog/goog.js'; @@ -34,6 +35,7 @@ import {PathObject} from './path_object.js'; /** * The base class for a block renderer. + * * @alias Blockly.blockRendering.Renderer */ export class Renderer implements IRegistrable { @@ -45,6 +47,7 @@ export class Renderer implements IRegistrable { /** * Rendering constant overrides, passed in through options. + * * @internal */ overrides: object|null = null; @@ -59,7 +62,8 @@ export class Renderer implements IRegistrable { /** * Gets the class name that identifies this renderer. - * @return The CSS class name. + * + * @returns The CSS class name. * @internal */ getClassName(): string { @@ -68,6 +72,7 @@ export class Renderer implements IRegistrable { /** * Initialize the renderer. + * * @param theme The workspace theme object. * @param opt_rendererOverrides Rendering constant overrides. * @internal @@ -84,6 +89,7 @@ export class Renderer implements IRegistrable { /** * Create any DOM elements that this renderer needs. + * * @param svg The root of the workspace's SVG. * @param theme The workspace theme object. * @internal @@ -96,6 +102,7 @@ export class Renderer implements IRegistrable { /** * Refresh the renderer after a theme change. + * * @param svg The root of the workspace's SVG. * @param theme The workspace theme object. * @internal @@ -117,6 +124,7 @@ export class Renderer implements IRegistrable { /** * Dispose of this renderer. * Delete all DOM elements that this renderer and its constants created. + * * @internal */ dispose() { @@ -127,7 +135,8 @@ export class Renderer implements IRegistrable { /** * Create a new instance of the renderer's constant provider. - * @return The constant provider. + * + * @returns The constant provider. */ protected makeConstants_(): ConstantProvider { return new ConstantProvider(); @@ -135,8 +144,9 @@ export class Renderer implements IRegistrable { /** * Create a new instance of the renderer's render info object. + * * @param block The block to measure. - * @return The render info object. + * @returns The render info object. */ protected makeRenderInfo_(block: BlockSvg): RenderInfo { return new RenderInfo(this, block); @@ -144,10 +154,11 @@ export class Renderer implements IRegistrable { /** * Create a new instance of the renderer's drawer. + * * @param block The block to render. * @param info An object containing all information needed to render this * block. - * @return The drawer. + * @returns The drawer. */ protected makeDrawer_(block: BlockSvg, info: RenderInfo): Drawer { return new Drawer(block, info); @@ -155,7 +166,8 @@ export class Renderer implements IRegistrable { /** * Create a new instance of the renderer's debugger. - * @return The renderer debugger. + * + * @returns The renderer debugger. * @suppress {strictModuleDepCheck} Debug renderer only included in * playground. */ @@ -165,9 +177,10 @@ export class Renderer implements IRegistrable { /** * Create a new instance of the renderer's marker drawer. + * * @param workspace The workspace the marker belongs to. * @param marker The marker. - * @return The object in charge of drawing the marker. + * @returns The object in charge of drawing the marker. * @internal */ makeMarkerDrawer(workspace: WorkspaceSvg, marker: Marker): MarkerSvg { @@ -176,9 +189,10 @@ export class Renderer implements IRegistrable { /** * Create a new instance of a renderer path object. + * * @param root The root SVG element. * @param style The style object to use for colouring. - * @return The renderer path object. + * @returns The renderer path object. * @internal */ makePathObject(root: SVGElement, style: BlockStyle): IPathObject { @@ -188,7 +202,8 @@ export class Renderer implements IRegistrable { /** * Get the current renderer's constant provider. We assume that when this is * called, the renderer has already been initialized. - * @return The constant provider. + * + * @returns The constant provider. * @internal */ getConstants(): ConstantProvider { @@ -197,8 +212,9 @@ export class Renderer implements IRegistrable { /** * Determine whether or not to highlight a connection. + * * @param _conn The connection to determine whether or not to highlight. - * @return True if we should highlight the connection. + * @returns True if we should highlight the connection. * @internal */ shouldHighlightConnection(_conn: Connection): boolean { @@ -210,11 +226,12 @@ export class Renderer implements IRegistrable { * block-clump. If the clump is a row the end is the last input. If the clump * is a stack, the end is the last next connection. If the clump is neither, * then this returns false. + * * @param topBlock The top block of the block clump we want to try and connect * to. * @param orphanBlock The orphan block that wants to find a home. * @param localType The type of the connection being dragged. - * @return Whether there is a home for the orphan or not. + * @returns Whether there is a home for the orphan or not. * @internal */ orphanCanConnectAtEnd( @@ -229,10 +246,11 @@ export class Renderer implements IRegistrable { /** * Chooses a connection preview method based on the available connection, the * current dragged connection, and the block being dragged. + * * @param closest The available connection. * @param local The connection currently being dragged. * @param topBlock The block currently being dragged. - * @return The preview type to display. + * @returns The preview type to display. * @internal */ getConnectionPreviewMethod( @@ -253,6 +271,7 @@ export class Renderer implements IRegistrable { /** * Render the block. + * * @param block The block to render. * @internal */ diff --git a/core/renderers/geras/constants.ts b/core/renderers/geras/constants.ts index beb269d3c..532ccb032 100644 --- a/core/renderers/geras/constants.ts +++ b/core/renderers/geras/constants.ts @@ -7,6 +7,7 @@ /** * An object that provides constants for rendering blocks in Geras * mode. + * * @class */ import * as goog from '../../../closure/goog/goog.js'; @@ -17,6 +18,7 @@ import {ConstantProvider as BaseConstantProvider} from '../common/constants.js'; /** * An object that provides constants for rendering blocks in Geras mode. + * * @alias Blockly.geras.ConstantProvider */ export class ConstantProvider extends BaseConstantProvider { diff --git a/core/renderers/geras/drawer.ts b/core/renderers/geras/drawer.ts index d07ad61aa..e3546cf77 100644 --- a/core/renderers/geras/drawer.ts +++ b/core/renderers/geras/drawer.ts @@ -6,6 +6,7 @@ /** * Renderer that preserves the look and feel of Blockly pre-2019. + * * @class */ import * as goog from '../../../closure/goog/goog.js'; @@ -26,6 +27,7 @@ import type {PathObject} from './path_object.js'; /** * An object that draws a block based on the given rendering information. + * * @alias Blockly.geras.Drawer */ export class Drawer extends BaseDrawer { diff --git a/core/renderers/geras/geras.ts b/core/renderers/geras/geras.ts index cbeaba916..9fec7d134 100644 --- a/core/renderers/geras/geras.ts +++ b/core/renderers/geras/geras.ts @@ -1,4 +1,4 @@ -/** @fileoverview Re-exports of Blockly.geras.* modules. */ +/** @file Re-exports of Blockly.geras.* modules. */ /** * @license @@ -8,6 +8,7 @@ /** * Re-exports of Blockly.geras.* modules. + * * @namespace Blockly.geras */ import * as goog from '../../../closure/goog/goog.js'; diff --git a/core/renderers/geras/highlight_constants.ts b/core/renderers/geras/highlight_constants.ts index f9ef7e6aa..fab2ec9b9 100644 --- a/core/renderers/geras/highlight_constants.ts +++ b/core/renderers/geras/highlight_constants.ts @@ -6,6 +6,7 @@ /** * Objects for rendering highlights on blocks. + * * @class */ import * as goog from '../../../closure/goog/goog.js'; @@ -63,6 +64,7 @@ export interface JaggedTeeth { * Some highlights are simple offsets of the parent paths and can be generated * programmatically. Others, especially on curves, are just made out of piles * of constants and are hard to tweak. + * * @alias Blockly.geras.HighlightConstantProvider */ export class HighlightConstantProvider { @@ -94,6 +96,7 @@ export class HighlightConstantProvider { /** * The start point, which is offset in both X and Y, as an SVG path chunk. + * * @internal */ this.START_POINT = svgPaths.moveBy(this.OFFSET, this.OFFSET); @@ -101,6 +104,7 @@ export class HighlightConstantProvider { /** * Initialize shape objects based on the constants set in the constructor. + * * @internal */ init() { @@ -141,7 +145,7 @@ export class HighlightConstantProvider { } /** - * @return An object containing sizing and path information about inside + * @returns An object containing sizing and path information about inside * corner highlights. * @internal */ @@ -185,7 +189,7 @@ export class HighlightConstantProvider { } /** - * @return An object containing sizing and path information about outside + * @returns An object containing sizing and path information about outside * corner highlights. * @internal */ @@ -234,7 +238,7 @@ export class HighlightConstantProvider { } /** - * @return An object containing sizing and path information about puzzle tab + * @returns An object containing sizing and path information about puzzle tab * highlights. * @internal */ @@ -284,7 +288,7 @@ export class HighlightConstantProvider { } /** - * @return An object containing sizing and path information about notch + * @returns An object containing sizing and path information about notch * highlights. * @internal */ @@ -296,7 +300,7 @@ export class HighlightConstantProvider { } /** - * @return An object containing sizing and path information about collapsed + * @returns An object containing sizing and path information about collapsed * block edge highlights. * @internal */ @@ -307,7 +311,7 @@ export class HighlightConstantProvider { } /** - * @return An object containing sizing and path information about start + * @returns An object containing sizing and path information about start * highlights. * @internal */ diff --git a/core/renderers/geras/highlighter.ts b/core/renderers/geras/highlighter.ts index 232db801f..6dbc1e73d 100644 --- a/core/renderers/geras/highlighter.ts +++ b/core/renderers/geras/highlighter.ts @@ -7,6 +7,7 @@ /** * Methods for adding highlights on block, for rendering in * compatibility mode. + * * @class */ import * as goog from '../../../closure/goog/goog.js'; @@ -39,6 +40,7 @@ import type {InlineInput} from './measurables/inline_input.js'; * position of each part of the block. The resulting paths are not continuous * or closed paths. The highlights for tabs and notches are loosely based on * tab and notch shapes, but are not exactly the same. + * * @alias Blockly.geras.Highlighter */ export class Highlighter { @@ -85,7 +87,8 @@ export class Highlighter { /** * Get the steps for the highlight path. - * @return The steps for the highlight path. + * + * @returns The steps for the highlight path. * @internal */ getPath(): string { @@ -94,6 +97,7 @@ export class Highlighter { /** * Add a highlight to the top corner of a block. + * * @param row The top row of the block. * @internal */ @@ -124,6 +128,7 @@ export class Highlighter { /** * Add a highlight on a jagged edge for a collapsed block. + * * @param row The row to highlight. * @internal */ @@ -138,6 +143,7 @@ export class Highlighter { /** * Add a highlight on a value input. + * * @param row The row the input belongs to. * @internal */ @@ -159,6 +165,7 @@ export class Highlighter { /** * Add a highlight on a statement input. + * * @param row The row to highlight. * @internal */ @@ -182,6 +189,7 @@ export class Highlighter { /** * Add a highlight on the right side of a row. + * * @param row The row to highlight. * @internal */ @@ -201,6 +209,7 @@ export class Highlighter { /** * Add a highlight to the bottom row. + * * @param row The row to highlight. * @internal */ @@ -225,6 +234,7 @@ export class Highlighter { /** * Draw the highlight on the left side of the block. + * * @internal */ drawLeft() { @@ -258,6 +268,7 @@ export class Highlighter { /** * Add a highlight to an inline input. + * * @param input The input to highlight. * @internal */ diff --git a/core/renderers/geras/info.ts b/core/renderers/geras/info.ts index a5a6edffd..17be507a0 100644 --- a/core/renderers/geras/info.ts +++ b/core/renderers/geras/info.ts @@ -7,6 +7,7 @@ /** * Old (compatibility) renderer. * Geras: spirit of old age. + * * @class */ import * as goog from '../../../closure/goog/goog.js'; @@ -38,6 +39,7 @@ import type {Renderer} from './renderer.js'; * This measure pass does not propagate changes to the block (although fields * may choose to rerender when getSize() is called). However, calling it * repeatedly may be expensive. + * * @alias Blockly.geras.RenderInfo */ export class RenderInfo extends BaseRenderInfo { @@ -58,7 +60,8 @@ export class RenderInfo extends BaseRenderInfo { /** * Get the block renderer in use. - * @return The block renderer in use. + * + * @returns The block renderer in use. * @internal */ override getRenderer(): Renderer { diff --git a/core/renderers/geras/measurables/inline_input.ts b/core/renderers/geras/measurables/inline_input.ts index 1ba4d7e44..be3b6578a 100644 --- a/core/renderers/geras/measurables/inline_input.ts +++ b/core/renderers/geras/measurables/inline_input.ts @@ -7,6 +7,7 @@ /** * Objects representing inline inputs with connections on a * rendered block. + * * @class */ import * as goog from '../../../../closure/goog/goog.js'; @@ -22,6 +23,7 @@ import type {ConstantProvider as GerasConstantProvider} from '../constants.js'; /** * An object containing information about the space an inline input takes up * during rendering. + * * @alias Blockly.geras.InlineInput */ export class InlineInput extends BaseInlineInput { diff --git a/core/renderers/geras/measurables/statement_input.ts b/core/renderers/geras/measurables/statement_input.ts index 494f320c7..2fa21fa11 100644 --- a/core/renderers/geras/measurables/statement_input.ts +++ b/core/renderers/geras/measurables/statement_input.ts @@ -7,6 +7,7 @@ /** * Objects representing statement inputs with connections on a * rendered block. + * * @class */ import * as goog from '../../../../closure/goog/goog.js'; @@ -22,6 +23,7 @@ import type {ConstantProvider as GerasConstantProvider} from '../constants.js'; /** * An object containing information about the space a statement input takes up * during rendering. + * * @alias Blockly.geras.StatementInput */ export class StatementInput extends BaseStatementInput { diff --git a/core/renderers/geras/path_object.ts b/core/renderers/geras/path_object.ts index 78758e986..f331ff6d7 100644 --- a/core/renderers/geras/path_object.ts +++ b/core/renderers/geras/path_object.ts @@ -6,6 +6,7 @@ /** * An object that owns a block's rendering SVG elements. + * * @class */ import * as goog from '../../../closure/goog/goog.js'; @@ -28,6 +29,7 @@ import type {ConstantProvider} from './constants.js'; /** * An object that handles creating and setting each of the SVG elements * used by the renderer. + * * @alias Blockly.geras.PathObject */ export class PathObject extends BasePathObject { @@ -38,6 +40,7 @@ export class PathObject extends BasePathObject { /** * The colour of the dark path on the block in '#RRGGBB' format. + * * @internal */ colourDark = '#000000'; @@ -74,6 +77,7 @@ export class PathObject extends BasePathObject { /** * Set the highlight path generated by the renderer onto the SVG element. + * * @param highlightPath The highlight path. * @internal */ diff --git a/core/renderers/geras/renderer.ts b/core/renderers/geras/renderer.ts index 4a3cb907f..e27b09e7f 100644 --- a/core/renderers/geras/renderer.ts +++ b/core/renderers/geras/renderer.ts @@ -6,6 +6,7 @@ /** * Geras renderer. + * * @class */ import * as goog from '../../../closure/goog/goog.js'; @@ -30,6 +31,7 @@ import {PathObject} from './path_object.js'; /** * The geras renderer. + * * @alias Blockly.geras.Renderer */ export class Renderer extends BaseRenderer { @@ -50,6 +52,9 @@ export class Renderer extends BaseRenderer { /** * Initialize the renderer. Geras has a highlight provider in addition to * the normal constant provider. + * + * @param theme + * @param opt_rendererOverrides * @internal */ override init(theme: Theme, opt_rendererOverrides: AnyDuringMigration) { @@ -69,8 +74,9 @@ export class Renderer extends BaseRenderer { /** * Create a new instance of the renderer's render info object. + * * @param block The block to measure. - * @return The render info object. + * @returns The render info object. */ protected override makeRenderInfo_(block: BlockSvg): RenderInfo { return new RenderInfo(this, block); @@ -78,10 +84,11 @@ export class Renderer extends BaseRenderer { /** * Create a new instance of the renderer's drawer. + * * @param block The block to render. * @param info An object containing all information needed to render this * block. - * @return The drawer. + * @returns The drawer. */ protected override makeDrawer_(block: BlockSvg, info: BaseRenderInfo): Drawer { @@ -90,9 +97,10 @@ export class Renderer extends BaseRenderer { /** * Create a new instance of a renderer path object. + * * @param root The root SVG element. * @param style The style object to use for colouring. - * @return The renderer path object. + * @returns The renderer path object. * @internal */ override makePathObject(root: SVGElement, style: BlockStyle): PathObject { @@ -102,7 +110,8 @@ export class Renderer extends BaseRenderer { /** * Create a new instance of the renderer's highlight constant provider. - * @return The highlight constant provider. + * + * @returns The highlight constant provider. */ protected makeHighlightConstants_(): HighlightConstantProvider { return new HighlightConstantProvider((this.getConstants())); @@ -111,7 +120,8 @@ export class Renderer extends BaseRenderer { /** * Get the renderer's highlight constant provider. We assume that when this * is called, the renderer has already been initialized. - * @return The highlight constant provider. + * + * @returns The highlight constant provider. * @internal */ getHighlightConstants(): HighlightConstantProvider { diff --git a/core/renderers/measurables/base.ts b/core/renderers/measurables/base.ts index 0d5e560bb..78346db87 100644 --- a/core/renderers/measurables/base.ts +++ b/core/renderers/measurables/base.ts @@ -6,6 +6,7 @@ /** * Methods for graphically rendering a block as SVG. + * * @class */ import * as goog from '../../../closure/goog/goog.js'; @@ -20,6 +21,7 @@ import {Types} from './types.js'; * The base class to represent a part of a block that takes up space during * rendering. The constructor for each non-spacer Measurable records the size * of the block element (e.g. field, statement input). + * * @alias Blockly.blockRendering.Measurable */ export class Measurable { diff --git a/core/renderers/measurables/bottom_row.ts b/core/renderers/measurables/bottom_row.ts index 7d1d0ce94..e731dd228 100644 --- a/core/renderers/measurables/bottom_row.ts +++ b/core/renderers/measurables/bottom_row.ts @@ -7,6 +7,7 @@ /** * Object representing a bottom row on a rendered block. * of its subcomponents. + * * @class */ import * as goog from '../../../closure/goog/goog.js'; @@ -25,18 +26,21 @@ import {Types} from './types.js'; * a block as well as spacing information for the bottom row. * Elements in a bottom row can consist of corners, spacers and next * connections. + * * @struct * @alias Blockly.blockRendering.BottomRow */ export class BottomRow extends Row { /** * Whether this row has a next connection. + * * @internal */ hasNextConnection = false; /** * The next connection on the row, if any. + * * @internal */ connection: NextConnection|null = null; @@ -45,6 +49,7 @@ export class BottomRow extends Row { * The amount that the bottom of the block extends below the horizontal * edge, e.g. because of a next connection. Must be non-negative (see * #2820). + * * @internal */ descenderHeight = 0; @@ -66,8 +71,9 @@ export class BottomRow extends Row { /** * Returns whether or not the bottom row has a left square corner. + * * @param block The block whose bottom row this represents. - * @return Whether or not the bottom row has a left square corner. + * @returns Whether or not the bottom row has a left square corner. */ hasLeftSquareCorner(block: BlockSvg): boolean { return !!block.outputConnection || !!block.getNextBlock(); @@ -75,8 +81,9 @@ export class BottomRow extends Row { /** * Returns whether or not the bottom row has a right square corner. + * * @param _block The block whose bottom row this represents. - * @return Whether or not the bottom row has a right square corner. + * @returns Whether or not the bottom row has a right square corner. */ hasRightSquareCorner(_block: BlockSvg): boolean { return true; diff --git a/core/renderers/measurables/connection.ts b/core/renderers/measurables/connection.ts index 790dc0930..ab4dbcd37 100644 --- a/core/renderers/measurables/connection.ts +++ b/core/renderers/measurables/connection.ts @@ -7,6 +7,7 @@ /** * Base class representing the space a connection takes up during * rendering. + * * @class */ import * as goog from '../../../closure/goog/goog.js'; @@ -23,6 +24,7 @@ import {Types} from './types.js'; /** * The base class to represent a connection and the space that it takes up on * the block. + * * @alias Blockly.blockRendering.Connection */ export class Connection extends Measurable { diff --git a/core/renderers/measurables/external_value_input.ts b/core/renderers/measurables/external_value_input.ts index deb1ccd9e..8ec17867f 100644 --- a/core/renderers/measurables/external_value_input.ts +++ b/core/renderers/measurables/external_value_input.ts @@ -7,6 +7,7 @@ /** * Class representing external value inputs with connections on a * rendered block. + * * @class */ import * as goog from '../../../closure/goog/goog.js'; @@ -23,6 +24,7 @@ import {Types} from './types.js'; /** * An object containing information about the space an external value input * takes up during rendering + * * @struct * @alias Blockly.blockRendering.ExternalValueInput */ diff --git a/core/renderers/measurables/field.ts b/core/renderers/measurables/field.ts index f8f4992ce..b327ba697 100644 --- a/core/renderers/measurables/field.ts +++ b/core/renderers/measurables/field.ts @@ -7,6 +7,7 @@ /** * Objects representing a field in a row of a rendered * block. + * * @class */ import * as goog from '../../../closure/goog/goog.js'; @@ -24,6 +25,7 @@ import {Types} from './types.js'; /** * An object containing information about the space a field takes up during * rendering + * * @struct * @alias Blockly.blockRendering.Field */ diff --git a/core/renderers/measurables/hat.ts b/core/renderers/measurables/hat.ts index fe519becd..7a7acca3d 100644 --- a/core/renderers/measurables/hat.ts +++ b/core/renderers/measurables/hat.ts @@ -7,6 +7,7 @@ /** * Objects representing a hat in a row of a rendered * block. + * * @class */ import * as goog from '../../../closure/goog/goog.js'; @@ -21,6 +22,7 @@ import {Types} from './types.js'; /** * An object containing information about the space a hat takes up during * rendering. + * * @struct * @alias Blockly.blockRendering.Hat */ diff --git a/core/renderers/measurables/icon.ts b/core/renderers/measurables/icon.ts index 0b1d6d473..1979f84e0 100644 --- a/core/renderers/measurables/icon.ts +++ b/core/renderers/measurables/icon.ts @@ -7,6 +7,7 @@ /** * Objects representing an icon in a row of a rendered * block. + * * @class */ import * as goog from '../../../closure/goog/goog.js'; @@ -23,6 +24,7 @@ import {Types} from './types.js'; /** * An object containing information about the space an icon takes up during * rendering + * * @struct * @alias Blockly.blockRendering.Icon */ @@ -32,6 +34,7 @@ export class Icon extends Measurable { /** * An object containing information about the space an icon takes up during * rendering + * * @param constants The rendering constants provider. * @param icon The icon to measure and store information for. * @internal diff --git a/core/renderers/measurables/in_row_spacer.ts b/core/renderers/measurables/in_row_spacer.ts index f72a75b94..909b1ea35 100644 --- a/core/renderers/measurables/in_row_spacer.ts +++ b/core/renderers/measurables/in_row_spacer.ts @@ -7,6 +7,7 @@ /** * Objects representing a spacer in a row of a rendered * block. + * * @class */ import * as goog from '../../../closure/goog/goog.js'; @@ -21,6 +22,7 @@ import {Types} from './types.js'; /** * An object containing information about a spacer between two elements on a * row. + * * @struct * @alias Blockly.blockRendering.InRowSpacer */ diff --git a/core/renderers/measurables/inline_input.ts b/core/renderers/measurables/inline_input.ts index 6eec6706a..b66f7f7bb 100644 --- a/core/renderers/measurables/inline_input.ts +++ b/core/renderers/measurables/inline_input.ts @@ -7,6 +7,7 @@ /** * Class representing inline inputs with connections on a rendered * block. + * * @class */ import * as goog from '../../../closure/goog/goog.js'; @@ -23,6 +24,7 @@ import {Types} from './types.js'; /** * An object containing information about the space an inline input takes up * during rendering + * * @struct * @alias Blockly.blockRendering.InlineInput */ diff --git a/core/renderers/measurables/input_connection.ts b/core/renderers/measurables/input_connection.ts index 9d2761096..46c7c9cdd 100644 --- a/core/renderers/measurables/input_connection.ts +++ b/core/renderers/measurables/input_connection.ts @@ -6,6 +6,7 @@ /** * Class representing inputs with connections on a rendered block. + * * @class */ import * as goog from '../../../closure/goog/goog.js'; @@ -23,6 +24,7 @@ import {Types} from './types.js'; /** * The base class to represent an input that takes up space on a block * during rendering + * * @alias Blockly.blockRendering.InputConnection */ export class InputConnection extends Connection { diff --git a/core/renderers/measurables/input_row.ts b/core/renderers/measurables/input_row.ts index 6045759db..f3ad0a1ee 100644 --- a/core/renderers/measurables/input_row.ts +++ b/core/renderers/measurables/input_row.ts @@ -7,6 +7,7 @@ /** * Object representing a row that holds one or more inputs on a * rendered block. + * * @class */ import * as goog from '../../../closure/goog/goog.js'; @@ -23,12 +24,14 @@ import {Types} from './types.js'; /** * An object containing information about a row that holds one or more inputs. + * * @struct * @alias Blockly.blockRendering.InputRow */ export class InputRow extends Row { /** * The total width of all blocks connected to this row. + * * @internal */ connectedBlockWidths = 0; @@ -44,6 +47,7 @@ export class InputRow extends Row { /** * Inspect all subcomponents and populate all size properties on the row. + * * @internal */ override measure() { diff --git a/core/renderers/measurables/jagged_edge.ts b/core/renderers/measurables/jagged_edge.ts index 2c1368588..10829556f 100644 --- a/core/renderers/measurables/jagged_edge.ts +++ b/core/renderers/measurables/jagged_edge.ts @@ -7,6 +7,7 @@ /** * Objects representing a jagged edge in a row of a rendered * block. + * * @class */ import * as goog from '../../../closure/goog/goog.js'; @@ -21,6 +22,7 @@ import {Types} from './types.js'; /** * An object containing information about the jagged edge of a collapsed block * takes up during rendering + * * @struct * @alias Blockly.blockRendering.JaggedEdge */ diff --git a/core/renderers/measurables/next_connection.ts b/core/renderers/measurables/next_connection.ts index cc8186ef8..0ab541bcf 100644 --- a/core/renderers/measurables/next_connection.ts +++ b/core/renderers/measurables/next_connection.ts @@ -7,6 +7,7 @@ /** * Class representing the space a next connection takes up during * rendering. + * * @class */ import * as goog from '../../../closure/goog/goog.js'; @@ -22,6 +23,7 @@ import {Types} from './types.js'; /** * An object containing information about the space a next connection takes * up during rendering. + * * @struct * @alias Blockly.blockRendering.NextConnection */ diff --git a/core/renderers/measurables/output_connection.ts b/core/renderers/measurables/output_connection.ts index 705235a3d..5f668d3ef 100644 --- a/core/renderers/measurables/output_connection.ts +++ b/core/renderers/measurables/output_connection.ts @@ -7,6 +7,7 @@ /** * Class representing the space a output connection takes up * during rendering. + * * @class */ import * as goog from '../../../closure/goog/goog.js'; @@ -22,6 +23,7 @@ import {Types} from './types.js'; /** * An object containing information about the space an output connection takes * up during rendering. + * * @struct * @alias Blockly.blockRendering.OutputConnection */ diff --git a/core/renderers/measurables/previous_connection.ts b/core/renderers/measurables/previous_connection.ts index 157c34816..31ca71764 100644 --- a/core/renderers/measurables/previous_connection.ts +++ b/core/renderers/measurables/previous_connection.ts @@ -7,6 +7,7 @@ /** * Class representing the space a previous connection takes up * during rendering. + * * @class */ import * as goog from '../../../closure/goog/goog.js'; @@ -22,6 +23,7 @@ import {Types} from './types.js'; /** * An object containing information about the space a previous connection takes * up during rendering. + * * @struct * @alias Blockly.blockRendering.PreviousConnection */ diff --git a/core/renderers/measurables/round_corner.ts b/core/renderers/measurables/round_corner.ts index 31fcca87a..a19dc090c 100644 --- a/core/renderers/measurables/round_corner.ts +++ b/core/renderers/measurables/round_corner.ts @@ -7,6 +7,7 @@ /** * Objects representing a round corner in a row of a rendered * block. + * * @class */ import * as goog from '../../../closure/goog/goog.js'; @@ -21,6 +22,7 @@ import {Types} from './types.js'; /** * An object containing information about the space a rounded corner takes up * during rendering. + * * @struct * @alias Blockly.blockRendering.RoundCorner */ diff --git a/core/renderers/measurables/row.ts b/core/renderers/measurables/row.ts index 744938353..3b34b623f 100644 --- a/core/renderers/measurables/row.ts +++ b/core/renderers/measurables/row.ts @@ -6,6 +6,7 @@ /** * Object representing a single row on a rendered block. + * * @class */ import * as goog from '../../../closure/goog/goog.js'; @@ -22,6 +23,7 @@ import {Types} from './types.js'; /** * An object representing a single row on a rendered block and all of its * subcomponents. + * * @alias Blockly.blockRendering.Row */ export class Row { @@ -30,12 +32,14 @@ export class Row { /** * An array of elements contained in this row. + * * @internal */ elements: Measurable[] = []; /** * The height of the row. + * * @internal */ height = 0; @@ -43,12 +47,14 @@ export class Row { /** * The width of the row, from the left edge of the block to the right. * Does not include child blocks unless they are inline. + * * @internal */ width = 0; /** * The minimum height of the row. + * * @internal */ minHeight = 0; @@ -56,6 +62,7 @@ export class Row { /** * The minimum width of the row, from the left edge of the block to the * right. Does not include child blocks unless they are inline. + * * @internal */ minWidth = 0; @@ -63,6 +70,7 @@ export class Row { /** * The width of the row, from the left edge of the block to the edge of the * block or any connected child blocks. + * * @internal */ widthWithConnectedBlocks = 0; @@ -70,6 +78,7 @@ export class Row { /** * The Y position of the row relative to the origin of the block's svg * group. + * * @internal */ yPos = 0; @@ -77,18 +86,21 @@ export class Row { /** * The X position of the row relative to the origin of the block's svg * group. + * * @internal */ xPos = 0; /** * Whether the row has any external inputs. + * * @internal */ hasExternalInput = false; /** * Whether the row has any statement inputs. + * * @internal */ hasStatement = false; @@ -102,18 +114,21 @@ export class Row { /** * Whether the row has any inline inputs. + * * @internal */ hasInlineInput = false; /** * Whether the row has any dummy inputs. + * * @internal */ hasDummyInput = false; /** * Whether the row has a jagged edge. + * * @internal */ hasJaggedEdge = false; @@ -121,6 +136,7 @@ export class Row { /** * Alignment of the row. + * * @internal */ align: number|null = null; @@ -143,7 +159,8 @@ export class Row { /** * Get the last input on this row, if it has one. - * @return The last input on the row, or null. + * + * @returns The last input on the row, or null. * @internal */ getLastInput(): InputConnection { @@ -161,6 +178,7 @@ export class Row { /** * Inspect all subcomponents and populate all size properties on the row. + * * @internal */ measure() { @@ -169,7 +187,8 @@ export class Row { /** * Determines whether this row should start with an element spacer. - * @return Whether the row should start with a spacer. + * + * @returns Whether the row should start with a spacer. * @internal */ startsWithElemSpacer(): boolean { @@ -178,7 +197,8 @@ export class Row { /** * Determines whether this row should end with an element spacer. - * @return Whether the row should end with a spacer. + * + * @returns Whether the row should end with a spacer. * @internal */ endsWithElemSpacer(): boolean { @@ -187,7 +207,8 @@ export class Row { /** * Convenience method to get the first spacer element on this row. - * @return The first spacer element on this row. + * + * @returns The first spacer element on this row. * @internal */ getFirstSpacer(): InRowSpacer { @@ -204,7 +225,8 @@ export class Row { /** * Convenience method to get the last spacer element on this row. - * @return The last spacer element on this row. + * + * @returns The last spacer element on this row. * @internal */ getLastSpacer(): InRowSpacer { diff --git a/core/renderers/measurables/spacer_row.ts b/core/renderers/measurables/spacer_row.ts index d22cd2b68..d71b043e3 100644 --- a/core/renderers/measurables/spacer_row.ts +++ b/core/renderers/measurables/spacer_row.ts @@ -6,6 +6,7 @@ /** * Object representing a spacer between two rows. + * * @class */ import * as goog from '../../../closure/goog/goog.js'; @@ -20,6 +21,7 @@ import {Types} from './types.js'; /** * An object containing information about a spacer between two rows. + * * @struct * @alias Blockly.blockRendering.SpacerRow */ diff --git a/core/renderers/measurables/square_corner.ts b/core/renderers/measurables/square_corner.ts index f0b015b8b..91d2ef5a0 100644 --- a/core/renderers/measurables/square_corner.ts +++ b/core/renderers/measurables/square_corner.ts @@ -7,6 +7,7 @@ /** * Objects representing a square corner in a row of a rendered * block. + * * @class */ import * as goog from '../../../closure/goog/goog.js'; @@ -21,6 +22,7 @@ import {Types} from './types.js'; /** * An object containing information about the space a square corner takes up * during rendering. + * * @struct * @alias Blockly.blockRendering.SquareCorner */ diff --git a/core/renderers/measurables/statement_input.ts b/core/renderers/measurables/statement_input.ts index 76ea0ac86..d75082a4a 100644 --- a/core/renderers/measurables/statement_input.ts +++ b/core/renderers/measurables/statement_input.ts @@ -7,6 +7,7 @@ /** * Class representing statement inputs with connections on a * rendered block. + * * @class */ import * as goog from '../../../closure/goog/goog.js'; @@ -23,6 +24,7 @@ import {Types} from './types.js'; /** * An object containing information about the space a statement input takes up * during rendering + * * @struct * @alias Blockly.blockRendering.StatementInput */ diff --git a/core/renderers/measurables/top_row.ts b/core/renderers/measurables/top_row.ts index f804304c0..655ec01aa 100644 --- a/core/renderers/measurables/top_row.ts +++ b/core/renderers/measurables/top_row.ts @@ -6,6 +6,7 @@ /** * Object representing a top row on a rendered block. + * * @class */ import * as goog from '../../../closure/goog/goog.js'; @@ -27,6 +28,7 @@ import {Types} from './types.js'; * connections. * After this constructor is called, the row will contain all non-spacer * elements it needs. + * * @struct * @alias Blockly.blockRendering.TopRow */ @@ -35,6 +37,7 @@ export class TopRow extends Row { * The starting point for drawing the row, in the y direction. * This allows us to draw hats and similar shapes that don't start at the * origin. Must be non-negative (see #2820). + * * @internal */ capline = 0; @@ -61,8 +64,9 @@ export class TopRow extends Row { /** * Returns whether or not the top row has a left square corner. + * * @param block The block whose top row this represents. - * @return Whether or not the top row has a left square corner. + * @returns Whether or not the top row has a left square corner. * @internal */ hasLeftSquareCorner(block: BlockSvg): boolean { @@ -77,8 +81,9 @@ export class TopRow extends Row { /** * Returns whether or not the top row has a right square corner. + * * @param _block The block whose top row this represents. - * @return Whether or not the top row has a right square corner. + * @returns Whether or not the top row has a right square corner. */ hasRightSquareCorner(_block: BlockSvg): boolean { return true; diff --git a/core/renderers/measurables/types.ts b/core/renderers/measurables/types.ts index a42099177..d4be3297a 100644 --- a/core/renderers/measurables/types.ts +++ b/core/renderers/measurables/types.ts @@ -6,6 +6,7 @@ /** * Measurable types. + * * @namespace Blockly.blockRendering.Types */ import * as goog from '../../../closure/goog/goog.js'; @@ -17,6 +18,7 @@ import type {Row} from './row.js'; /** * Types of rendering elements. + * * @alias Blockly.blockRendering.Types */ class TypesContainer { @@ -50,12 +52,14 @@ class TypesContainer { /** * A Left Corner Union Type. + * * @internal */ LEFT_CORNER = this.LEFT_SQUARE_CORNER | this.LEFT_ROUND_CORNER; /** * A Right Corner Union Type. + * * @internal */ RIGHT_CORNER = this.RIGHT_SQUARE_CORNER | this.RIGHT_ROUND_CORNER; @@ -70,8 +74,9 @@ class TypesContainer { /** * Get the enum flag value of an existing type or register a new type. + * * @param type The name of the type. - * @return The enum flag value associated with that type. + * @returns The enum flag value associated with that type. * @internal */ getType(type: string): number { @@ -84,8 +89,9 @@ class TypesContainer { /** * Whether a measurable stores information about a field. + * * @param elem The element to check. - * @return 1 if the object stores information about a field. + * @returns 1 if the object stores information about a field. * @internal */ isField(elem: Measurable): number { @@ -94,8 +100,9 @@ class TypesContainer { /** * Whether a measurable stores information about a hat. + * * @param elem The element to check. - * @return 1 if the object stores information about a hat. + * @returns 1 if the object stores information about a hat. * @internal */ isHat(elem: Measurable): number { @@ -104,8 +111,9 @@ class TypesContainer { /** * Whether a measurable stores information about an icon. + * * @param elem The element to check. - * @return 1 if the object stores information about an icon. + * @returns 1 if the object stores information about an icon. * @internal */ isIcon(elem: Measurable): number { @@ -114,8 +122,9 @@ class TypesContainer { /** * Whether a measurable stores information about a spacer. + * * @param elem The element to check. - * @return 1 if the object stores information about a spacer. + * @returns 1 if the object stores information about a spacer. * @internal */ isSpacer(elem: Measurable|Row): number { @@ -124,8 +133,9 @@ class TypesContainer { /** * Whether a measurable stores information about an in-row spacer. + * * @param elem The element to check. - * @return 1 if the object stores information about an in-row spacer. + * @returns 1 if the object stores information about an in-row spacer. * @internal */ isInRowSpacer(elem: Measurable): number { @@ -134,8 +144,9 @@ class TypesContainer { /** * Whether a measurable stores information about an input. + * * @param elem The element to check. - * @return 1 if the object stores information about an input. + * @returns 1 if the object stores information about an input. * @internal */ isInput(elem: Measurable): number { @@ -144,8 +155,9 @@ class TypesContainer { /** * Whether a measurable stores information about an external input. + * * @param elem The element to check. - * @return 1 if the object stores information about an external input. + * @returns 1 if the object stores information about an external input. * @internal */ isExternalInput(elem: Measurable): number { @@ -154,8 +166,9 @@ class TypesContainer { /** * Whether a measurable stores information about an inline input. + * * @param elem The element to check. - * @return 1 if the object stores information about an inline input. + * @returns 1 if the object stores information about an inline input. * @internal */ isInlineInput(elem: Measurable): number { @@ -164,8 +177,9 @@ class TypesContainer { /** * Whether a measurable stores information about a statement input. + * * @param elem The element to check. - * @return 1 if the object stores information about a statement input. + * @returns 1 if the object stores information about a statement input. * @internal */ isStatementInput(elem: Measurable): number { @@ -174,8 +188,9 @@ class TypesContainer { /** * Whether a measurable stores information about a previous connection. + * * @param elem The element to check. - * @return 1 if the object stores information about a previous connection. + * @returns 1 if the object stores information about a previous connection. * @internal */ isPreviousConnection(elem: Measurable): number { @@ -184,8 +199,9 @@ class TypesContainer { /** * Whether a measurable stores information about a next connection. + * * @param elem The element to check. - * @return 1 if the object stores information about a next connection. + * @returns 1 if the object stores information about a next connection. * @internal */ isNextConnection(elem: Measurable): number { @@ -195,8 +211,9 @@ class TypesContainer { /** * Whether a measurable stores information about a previous or next * connection. + * * @param elem The element to check. - * @return 1 if the object stores information about a previous or next + * @returns 1 if the object stores information about a previous or next * connection. * @internal */ @@ -206,8 +223,9 @@ class TypesContainer { /** * Whether a measurable stores information about a left round corner. + * * @param elem The element to check. - * @return 1 if the object stores information about a left round corner. + * @returns 1 if the object stores information about a left round corner. * @internal */ isLeftRoundedCorner(elem: Measurable): number { @@ -216,8 +234,9 @@ class TypesContainer { /** * Whether a measurable stores information about a right round corner. + * * @param elem The element to check. - * @return 1 if the object stores information about a right round corner. + * @returns 1 if the object stores information about a right round corner. * @internal */ isRightRoundedCorner(elem: Measurable): number { @@ -226,8 +245,9 @@ class TypesContainer { /** * Whether a measurable stores information about a left square corner. + * * @param elem The element to check. - * @return 1 if the object stores information about a left square corner. + * @returns 1 if the object stores information about a left square corner. * @internal */ isLeftSquareCorner(elem: Measurable): number { @@ -236,8 +256,9 @@ class TypesContainer { /** * Whether a measurable stores information about a right square corner. + * * @param elem The element to check. - * @return 1 if the object stores information about a right square corner. + * @returns 1 if the object stores information about a right square corner. * @internal */ isRightSquareCorner(elem: Measurable): number { @@ -246,8 +267,9 @@ class TypesContainer { /** * Whether a measurable stores information about a corner. + * * @param elem The element to check. - * @return 1 if the object stores information about a corner. + * @returns 1 if the object stores information about a corner. * @internal */ isCorner(elem: Measurable): number { @@ -256,8 +278,9 @@ class TypesContainer { /** * Whether a measurable stores information about a jagged edge. + * * @param elem The element to check. - * @return 1 if the object stores information about a jagged edge. + * @returns 1 if the object stores information about a jagged edge. * @internal */ isJaggedEdge(elem: Measurable): number { @@ -266,8 +289,9 @@ class TypesContainer { /** * Whether a measurable stores information about a row. + * * @param row The row to check. - * @return 1 if the object stores information about a row. + * @returns 1 if the object stores information about a row. * @internal */ isRow(row: Row): number { @@ -276,8 +300,9 @@ class TypesContainer { /** * Whether a measurable stores information about a between-row spacer. + * * @param row The row to check. - * @return 1 if the object stores information about a between-row spacer. + * @returns 1 if the object stores information about a between-row spacer. * @internal */ isBetweenRowSpacer(row: Row): number { @@ -286,8 +311,9 @@ class TypesContainer { /** * Whether a measurable stores information about a top row. + * * @param row The row to check. - * @return 1 if the object stores information about a top row. + * @returns 1 if the object stores information about a top row. * @internal */ isTopRow(row: Row): number { @@ -296,8 +322,9 @@ class TypesContainer { /** * Whether a measurable stores information about a bottom row. + * * @param row The row to check. - * @return 1 if the object stores information about a bottom row. + * @returns 1 if the object stores information about a bottom row. * @internal */ isBottomRow(row: Row): number { @@ -306,8 +333,9 @@ class TypesContainer { /** * Whether a measurable stores information about a top or bottom row. + * * @param row The row to check. - * @return 1 if the object stores information about a top or bottom row. + * @returns 1 if the object stores information about a top or bottom row. * @internal */ isTopOrBottomRow(row: Row): number { @@ -316,8 +344,9 @@ class TypesContainer { /** * Whether a measurable stores information about an input row. + * * @param row The row to check. - * @return 1 if the object stores information about an input row. + * @returns 1 if the object stores information about an input row. * @internal */ isInputRow(row: Row): number { diff --git a/core/renderers/minimalist/constants.ts b/core/renderers/minimalist/constants.ts index f928c4333..f9dc23aee 100644 --- a/core/renderers/minimalist/constants.ts +++ b/core/renderers/minimalist/constants.ts @@ -7,6 +7,7 @@ /** * An object that provides constants for rendering blocks in the * minimalist renderer. + * * @class */ import * as goog from '../../../closure/goog/goog.js'; @@ -17,6 +18,7 @@ import {ConstantProvider as BaseConstantProvider} from '../common/constants.js'; /** * An object that provides constants for rendering blocks in the sample. + * * @alias Blockly.minimalist.ConstantProvider */ export class ConstantProvider extends BaseConstantProvider { diff --git a/core/renderers/minimalist/drawer.ts b/core/renderers/minimalist/drawer.ts index 5fa9264eb..1027a8d9d 100644 --- a/core/renderers/minimalist/drawer.ts +++ b/core/renderers/minimalist/drawer.ts @@ -6,6 +6,7 @@ /** * Minimalist rendering drawer. + * * @class */ import * as goog from '../../../closure/goog/goog.js'; @@ -19,6 +20,7 @@ import type {RenderInfo} from './info.js'; /** * An object that draws a block based on the given rendering information. + * * @alias Blockly.minimalist.Drawer */ export class Drawer extends BaseDrawer { diff --git a/core/renderers/minimalist/info.ts b/core/renderers/minimalist/info.ts index 95a39ac14..07b254725 100644 --- a/core/renderers/minimalist/info.ts +++ b/core/renderers/minimalist/info.ts @@ -6,6 +6,7 @@ /** * Minimalist render info object. + * * @class */ import * as goog from '../../../closure/goog/goog.js'; @@ -23,6 +24,7 @@ import type {Renderer} from './renderer.js'; * This measure pass does not propagate changes to the block (although fields * may choose to rerender when getSize() is called). However, calling it * repeatedly may be expensive. + * * @alias Blockly.minimalist.RenderInfo */ export class RenderInfo extends BaseRenderInfo { @@ -37,7 +39,8 @@ export class RenderInfo extends BaseRenderInfo { /** * Get the block renderer in use. - * @return The block renderer in use. + * + * @returns The block renderer in use. * @internal */ override getRenderer(): Renderer { diff --git a/core/renderers/minimalist/minimalist.ts b/core/renderers/minimalist/minimalist.ts index a6f9dbcec..433104b3d 100644 --- a/core/renderers/minimalist/minimalist.ts +++ b/core/renderers/minimalist/minimalist.ts @@ -1,4 +1,4 @@ -/** @fileoverview Re-exports of Blockly.minimalist.* modules. */ +/** @file Re-exports of Blockly.minimalist.* modules. */ /** * @license @@ -8,6 +8,7 @@ /** * Re-exports of Blockly.minimalist.* modules. + * * @namespace Blockly.minimalist */ import * as goog from '../../../closure/goog/goog.js'; diff --git a/core/renderers/minimalist/renderer.ts b/core/renderers/minimalist/renderer.ts index f62141095..2a4a509ee 100644 --- a/core/renderers/minimalist/renderer.ts +++ b/core/renderers/minimalist/renderer.ts @@ -6,6 +6,7 @@ /** * Minimalist renderer. + * * @class */ import * as goog from '../../../closure/goog/goog.js'; @@ -23,6 +24,7 @@ import {RenderInfo} from './info.js'; /** * The minimalist renderer. + * * @alias Blockly.minimalist.Renderer */ export class Renderer extends BaseRenderer { @@ -36,7 +38,8 @@ export class Renderer extends BaseRenderer { /** * Create a new instance of the renderer's constant provider. - * @return The constant provider. + * + * @returns The constant provider. */ protected override makeConstants_(): ConstantProvider { return new ConstantProvider(); @@ -44,8 +47,9 @@ export class Renderer extends BaseRenderer { /** * Create a new instance of the renderer's render info object. + * * @param block The block to measure. - * @return The render info object. + * @returns The render info object. */ protected override makeRenderInfo_(block: BlockSvg): RenderInfo { return new RenderInfo(this, block); @@ -53,10 +57,11 @@ export class Renderer extends BaseRenderer { /** * Create a new instance of the renderer's drawer. + * * @param block The block to render. * @param info An object containing all information needed to render this * block. - * @return The drawer. + * @returns The drawer. */ protected override makeDrawer_(block: BlockSvg, info: BaseRenderInfo): Drawer { diff --git a/core/renderers/thrasos/info.ts b/core/renderers/thrasos/info.ts index b898dbe98..1175453d5 100644 --- a/core/renderers/thrasos/info.ts +++ b/core/renderers/thrasos/info.ts @@ -7,6 +7,7 @@ /** * New (evolving) renderer. * Thrasos: spirit of boldness. + * * @class */ import * as goog from '../../../closure/goog/goog.js'; @@ -31,6 +32,7 @@ import type {Renderer} from './renderer.js'; * This measure pass does not propagate changes to the block (although fields * may choose to rerender when getSize() is called). However, calling it * repeatedly may be expensive. + * * @alias Blockly.thrasos.RenderInfo */ export class RenderInfo extends BaseRenderInfo { @@ -49,7 +51,8 @@ export class RenderInfo extends BaseRenderInfo { /** * Get the block renderer in use. - * @return The block renderer in use. + * + * @returns The block renderer in use. * @internal */ override getRenderer(): Renderer { diff --git a/core/renderers/thrasos/renderer.ts b/core/renderers/thrasos/renderer.ts index 7a0017798..88d6732a4 100644 --- a/core/renderers/thrasos/renderer.ts +++ b/core/renderers/thrasos/renderer.ts @@ -6,6 +6,7 @@ /** * Thrasos renderer. + * * @class */ import * as goog from '../../../closure/goog/goog.js'; @@ -20,6 +21,7 @@ import {RenderInfo} from './info.js'; /** * The thrasos renderer. + * * @alias Blockly.thrasos.Renderer */ export class Renderer extends BaseRenderer { @@ -33,8 +35,9 @@ export class Renderer extends BaseRenderer { /** * Create a new instance of the renderer's render info object. + * * @param block The block to measure. - * @return The render info object. + * @returns The render info object. */ protected override makeRenderInfo_(block: BlockSvg): RenderInfo { return new RenderInfo(this, block); diff --git a/core/renderers/thrasos/thrasos.ts b/core/renderers/thrasos/thrasos.ts index 2be08faff..0854ca5ab 100644 --- a/core/renderers/thrasos/thrasos.ts +++ b/core/renderers/thrasos/thrasos.ts @@ -1,4 +1,4 @@ -/** @fileoverview Re-exports of Blockly.thrasos.* modules. */ +/** @file Re-exports of Blockly.thrasos.* modules. */ /** * @license @@ -8,6 +8,7 @@ /** * Re-exports of Blockly.thrasos.* modules. + * * @namespace Blockly.thrasos */ import * as goog from '../../../closure/goog/goog.js'; diff --git a/core/renderers/zelos/constants.ts b/core/renderers/zelos/constants.ts index d9d481406..6a7ccbf62 100644 --- a/core/renderers/zelos/constants.ts +++ b/core/renderers/zelos/constants.ts @@ -7,6 +7,7 @@ /** * An object that provides constants for rendering blocks in Zelos * mode. + * * @class */ import * as goog from '../../../closure/goog/goog.js'; @@ -37,6 +38,7 @@ export interface InsideCorners { /** * An object that provides constants for rendering blocks in Zelos mode. + * * @alias Blockly.zelos.ConstantProvider */ export class ConstantProvider extends BaseConstantProvider { @@ -72,6 +74,7 @@ export class ConstantProvider extends BaseConstantProvider { /** * Radius of the cursor for input and output connections. + * * @internal */ CURSOR_RADIUS = 5; @@ -128,6 +131,7 @@ export class ConstantProvider extends BaseConstantProvider { /** * The ID of the selected glow filter, or the empty string if no filter is * set. + * * @internal */ selectedGlowFilterId = ''; @@ -142,6 +146,7 @@ export class ConstantProvider extends BaseConstantProvider { /** * The ID of the replacement glow filter, or the empty string if no filter * is set. + * * @internal */ replacementGlowFilterId = ''; @@ -230,6 +235,7 @@ export class ConstantProvider extends BaseConstantProvider { * When a block with the outer shape contains an input block with the inner * shape on its left or right edge, the block elements are aligned such that * the padding specified is reached. + * * @internal */ this.SHAPE_IN_SHAPE_PADDING = { @@ -343,7 +349,8 @@ export class ConstantProvider extends BaseConstantProvider { /** * Create sizing and path information about a hexagonal shape. - * @return An object containing sizing and path information about a hexagonal + * + * @returns An object containing sizing and path information about a hexagonal * shape for connections. * @internal */ @@ -356,11 +363,12 @@ export class ConstantProvider extends BaseConstantProvider { * height. The 'up' and 'down' versions of the paths are the same, but the Y * sign flips. The 'left' and 'right' versions of the path are also the * same, but the X sign flips. + * * @param height The height of the block the connection is on. * @param up True if the path should be drawn from bottom to top, false * otherwise. * @param right True if the path is for the right side of the block. - * @return A path fragment describing a rounded connection. + * @returns A path fragment describing a rounded connection. */ function makeMainPath(height: number, up: boolean, right: boolean): string { const halfHeight = height / 2; @@ -405,7 +413,8 @@ export class ConstantProvider extends BaseConstantProvider { /** * Create sizing and path information about a rounded shape. - * @return An object containing sizing and path information about a rounded + * + * @returns An object containing sizing and path information about a rounded * shape for connections. * @internal */ @@ -421,11 +430,12 @@ export class ConstantProvider extends BaseConstantProvider { * drawn in between the two arcs. The 'up' and 'down' versions of the paths * are the same, but the Y sign flips. The 'up' and 'right' versions of the * path flip the sweep-flag which moves the arc at negative angles. + * * @param blockHeight The height of the block the connection is on. * @param up True if the path should be drawn from bottom to top, false * otherwise. * @param right True if the path is for the right side of the block. - * @return A path fragment describing a rounded connection. + * @returns A path fragment describing a rounded connection. */ function makeMainPath( blockHeight: number, up: boolean, right: boolean): string { @@ -476,7 +486,8 @@ export class ConstantProvider extends BaseConstantProvider { /** * Create sizing and path information about a squared shape. - * @return An object containing sizing and path information about a squared + * + * @returns An object containing sizing and path information about a squared * shape for connections. * @internal */ @@ -490,11 +501,12 @@ export class ConstantProvider extends BaseConstantProvider { * The 'left' and 'right' versions of the paths are the same, but the Y sign * flips. The 'up' and 'down' versions of the path determine where the * corner point is placed and in turn the direction of the corners. + * * @param height The height of the block the connection is on. * @param up True if the path should be drawn from bottom to top, false * otherwise. * @param right True if the path is for the right side of the block. - * @return A path fragment describing a squared connection. + * @returns A path fragment describing a squared connection. */ function makeMainPath(height: number, up: boolean, right: boolean): string { const innerHeight = height - radius * 2; @@ -590,9 +602,10 @@ export class ConstantProvider extends BaseConstantProvider { /** * Make the main path for the notch. + * * @param dir Direction multiplier to apply to horizontal offsets along the * path. Either 1 or -1. - * @return A path fragment describing a notch. + * @returns A path fragment describing a notch. */ function makeMainPath(dir: number): string { return svgPaths.curve( diff --git a/core/renderers/zelos/drawer.ts b/core/renderers/zelos/drawer.ts index 63b08d706..a9f6ea04c 100644 --- a/core/renderers/zelos/drawer.ts +++ b/core/renderers/zelos/drawer.ts @@ -6,6 +6,7 @@ /** * Zelos renderer. + * * @class */ import * as goog from '../../../closure/goog/goog.js'; @@ -29,6 +30,7 @@ import type {PathObject} from './path_object.js'; /** * An object that draws a block based on the given rendering information. + * * @alias Blockly.zelos.Drawer */ export class Drawer extends BaseDrawer { @@ -101,6 +103,7 @@ export class Drawer extends BaseDrawer { /** * Add steps for the right side of a row that does not have value or * statement input connections. + * * @param row The row to draw the side of. */ protected override drawRightSideRow_(row: Row) { diff --git a/core/renderers/zelos/info.ts b/core/renderers/zelos/info.ts index 731c96455..99945dc38 100644 --- a/core/renderers/zelos/info.ts +++ b/core/renderers/zelos/info.ts @@ -6,6 +6,7 @@ /** * Makecode/scratch-style renderer. + * * @class */ import * as goog from '../../../closure/goog/goog.js'; @@ -41,6 +42,7 @@ import type {Renderer} from './renderer.js'; * This measure pass does not propagate changes to the block (although fields * may choose to rerender when getSize() is called). However, calling it * repeatedly may be expensive. + * * @alias Blockly.zelos.RenderInfo */ export class RenderInfo extends BaseRenderInfo { @@ -104,7 +106,8 @@ export class RenderInfo extends BaseRenderInfo { /** * Get the block renderer in use. - * @return The block renderer in use. + * + * @returns The block renderer in use. * @internal */ override getRenderer(): Renderer { @@ -453,8 +456,9 @@ export class RenderInfo extends BaseRenderInfo { /** * Calculate the spacing to reduce the left and right edges by based on the * outer and inner connection shape. + * * @param elem The first or last element on a block. - * @return The amount of spacing to reduce the first or last spacer. + * @returns The amount of spacing to reduce the first or last spacer. */ protected getNegativeSpacing_(elem: Measurable): number { if (!elem) { diff --git a/core/renderers/zelos/marker_svg.ts b/core/renderers/zelos/marker_svg.ts index 3fd1c0ee6..c53451a25 100644 --- a/core/renderers/zelos/marker_svg.ts +++ b/core/renderers/zelos/marker_svg.ts @@ -6,6 +6,7 @@ /** * Methods for graphically rendering a marker as SVG. + * * @class */ import * as goog from '../../../closure/goog/goog.js'; @@ -26,6 +27,7 @@ import type {ConstantProvider as ZelosConstantProvider} from './constants.js'; /** * Class to draw a marker. + * * @alias Blockly.zelos.MarkerSvg */ export class MarkerSvg extends BaseMarkerSvg { @@ -47,6 +49,7 @@ export class MarkerSvg extends BaseMarkerSvg { /** * Position and display the marker for an input or an output connection. + * * @param curNode The node to draw the marker for. */ private showWithInputOutput_(curNode: ASTNode) { @@ -69,6 +72,7 @@ export class MarkerSvg extends BaseMarkerSvg { /** * Draw a rectangle around the block. + * * @param curNode The current node of the marker. */ override showWithBlock_(curNode: ASTNode) { @@ -85,6 +89,7 @@ export class MarkerSvg extends BaseMarkerSvg { /** * Position the circle we use for input and output connections. + * * @param x The x position of the circle. * @param y The y position of the circle. */ diff --git a/core/renderers/zelos/measurables/bottom_row.ts b/core/renderers/zelos/measurables/bottom_row.ts index 9b45615b4..e06255296 100644 --- a/core/renderers/zelos/measurables/bottom_row.ts +++ b/core/renderers/zelos/measurables/bottom_row.ts @@ -6,6 +6,7 @@ /** * An object representing the bottom row of a rendered block. + * * @class */ import * as goog from '../../../../closure/goog/goog.js'; @@ -21,6 +22,7 @@ import {BottomRow as BaseBottomRow} from '../../../renderers/measurables/bottom_ * a block as well as spacing information for the top row. * Elements in a bottom row can consist of corners, spacers and next * connections. + * * @alias Blockly.zelos.BottomRow */ export class BottomRow extends BaseBottomRow { @@ -36,12 +38,20 @@ export class BottomRow extends BaseBottomRow { return false; } - /** Render a round corner unless the block has an output connection. */ + /** + * Render a round corner unless the block has an output connection. + * + * @param block + */ override hasLeftSquareCorner(block: BlockSvg) { return !!block.outputConnection; } - /** Render a round corner unless the block has an output connection. */ + /** + * Render a round corner unless the block has an output connection. + * + * @param block + */ override hasRightSquareCorner(block: BlockSvg) { return !!block.outputConnection && !block.statementInputCount && !block.nextConnection; diff --git a/core/renderers/zelos/measurables/inputs.ts b/core/renderers/zelos/measurables/inputs.ts index 9ca0c5eb8..911313950 100644 --- a/core/renderers/zelos/measurables/inputs.ts +++ b/core/renderers/zelos/measurables/inputs.ts @@ -7,6 +7,7 @@ /** * Zelos specific objects representing inputs with connections on * a rendered block. + * * @class */ import * as goog from '../../../../closure/goog/goog.js'; @@ -21,6 +22,7 @@ import {StatementInput as BaseStatementInput} from '../../../renderers/measurabl /** * An object containing information about the space a statement input takes up * during rendering. + * * @alias Blockly.zelos.StatementInput */ export class StatementInput extends BaseStatementInput { diff --git a/core/renderers/zelos/measurables/row_elements.ts b/core/renderers/zelos/measurables/row_elements.ts index 80b713433..8448b541f 100644 --- a/core/renderers/zelos/measurables/row_elements.ts +++ b/core/renderers/zelos/measurables/row_elements.ts @@ -7,6 +7,7 @@ /** * Zelos specific objects representing elements in a row of a * rendered block. + * * @class */ import * as goog from '../../../../closure/goog/goog.js'; @@ -20,6 +21,7 @@ import {Types} from '../../../renderers/measurables/types.js'; /** * An object containing information about the space a right connection shape * takes up during rendering. + * * @alias Blockly.zelos.RightConnectionShape */ export class RightConnectionShape extends Measurable { diff --git a/core/renderers/zelos/measurables/top_row.ts b/core/renderers/zelos/measurables/top_row.ts index a27ec6713..6216315b7 100644 --- a/core/renderers/zelos/measurables/top_row.ts +++ b/core/renderers/zelos/measurables/top_row.ts @@ -6,6 +6,7 @@ /** * An object representing the top row of a rendered block. + * * @class */ import * as goog from '../../../../closure/goog/goog.js'; @@ -23,6 +24,7 @@ import {TopRow as BaseTopRow} from '../../../renderers/measurables/top_row.js'; * connections. * After this constructor is called, the row will contain all non-spacer * elements it needs. + * * @alias Blockly.zelos.TopRow */ export class TopRow extends BaseTopRow { @@ -38,7 +40,11 @@ export class TopRow extends BaseTopRow { return false; } - /** Render a round corner unless the block has an output connection. */ + /** + * Render a round corner unless the block has an output connection. + * + * @param block + */ override hasLeftSquareCorner(block: BlockSvg) { const hasHat = (block.hat ? block.hat === 'cap' : this.constants_.ADD_START_HATS) && @@ -46,7 +52,11 @@ export class TopRow extends BaseTopRow { return !!block.outputConnection || hasHat; } - /** Render a round corner unless the block has an output connection. */ + /** + * Render a round corner unless the block has an output connection. + * + * @param block + */ override hasRightSquareCorner(block: BlockSvg) { return !!block.outputConnection && !block.statementInputCount && !block.nextConnection; diff --git a/core/renderers/zelos/path_object.ts b/core/renderers/zelos/path_object.ts index d10bcc0b5..d021865ba 100644 --- a/core/renderers/zelos/path_object.ts +++ b/core/renderers/zelos/path_object.ts @@ -6,6 +6,7 @@ /** * An object that owns a block's rendering SVG elements. + * * @class */ import * as goog from '../../../closure/goog/goog.js'; @@ -28,6 +29,7 @@ import type {ConstantProvider} from './constants.js'; /** * An object that handles creating and setting each of the SVG elements * used by the renderer. + * * @alias Blockly.zelos.PathObject */ export class PathObject extends BasePathObject { @@ -140,6 +142,7 @@ export class PathObject extends BasePathObject { /** * Method that's called when the drawer is about to draw the block. + * * @internal */ beginDrawing() { @@ -151,6 +154,7 @@ export class PathObject extends BasePathObject { /** * Method that's called when the drawer is done drawing. + * * @internal */ endDrawing() { @@ -167,6 +171,7 @@ export class PathObject extends BasePathObject { /** * Set the path generated by the renderer for an outline path on the * respective outline path SVG element. + * * @param name The input name. * @param pathString The path. * @internal @@ -179,8 +184,9 @@ export class PathObject extends BasePathObject { /** * Create's an outline path for the specified input. + * * @param name The input name. - * @return The SVG outline path. + * @returns The SVG outline path. */ private getOutlinePath_(name: string): SVGElement { if (!this.outlines.has(name)) { @@ -202,6 +208,7 @@ export class PathObject extends BasePathObject { /** * Remove an outline path that is associated with the specified input. + * * @param name The input name. */ private removeOutlinePath_(name: string) { diff --git a/core/renderers/zelos/renderer.ts b/core/renderers/zelos/renderer.ts index 1c3d1cba3..19610426c 100644 --- a/core/renderers/zelos/renderer.ts +++ b/core/renderers/zelos/renderer.ts @@ -6,6 +6,7 @@ /** * Zelos renderer. + * * @class */ import * as goog from '../../../closure/goog/goog.js'; @@ -36,6 +37,7 @@ import {PathObject} from './path_object.js'; /** * The zelos renderer. + * * @alias Blockly.zelos.Renderer */ export class Renderer extends BaseRenderer { @@ -51,7 +53,8 @@ export class Renderer extends BaseRenderer { /** * Create a new instance of the renderer's constant provider. - * @return The constant provider. + * + * @returns The constant provider. */ protected override makeConstants_(): ConstantProvider { return new ConstantProvider(); @@ -59,8 +62,9 @@ export class Renderer extends BaseRenderer { /** * Create a new instance of the renderer's render info object. + * * @param block The block to measure. - * @return The render info object. + * @returns The render info object. */ protected override makeRenderInfo_(block: BlockSvg): RenderInfo { return new RenderInfo(this, block); @@ -68,10 +72,11 @@ export class Renderer extends BaseRenderer { /** * Create a new instance of the renderer's drawer. + * * @param block The block to render. * @param info An object containing all information needed to render this * block. - * @return The drawer. + * @returns The drawer. */ protected override makeDrawer_(block: BlockSvg, info: BaseRenderInfo): Drawer { @@ -80,9 +85,10 @@ export class Renderer extends BaseRenderer { /** * Create a new instance of the renderer's cursor drawer. + * * @param workspace The workspace the cursor belongs to. * @param marker The marker. - * @return The object in charge of drawing the marker. + * @returns The object in charge of drawing the marker. * @internal */ override makeMarkerDrawer(workspace: WorkspaceSvg, marker: Marker): @@ -92,9 +98,10 @@ export class Renderer extends BaseRenderer { /** * Create a new instance of a renderer path object. + * * @param root The root SVG element. * @param style The style object to use for colouring. - * @return The renderer path object. + * @returns The renderer path object. * @internal */ override makePathObject(root: SVGElement, style: BlockStyle): PathObject { @@ -105,7 +112,8 @@ export class Renderer extends BaseRenderer { /** * Get the current renderer's constant provider. We assume that when this is * called, the renderer has already been initialized. - * @return The constant provider. + * + * @returns The constant provider. */ override getConstants(): ConstantProvider { return this.constants_; diff --git a/core/renderers/zelos/zelos.ts b/core/renderers/zelos/zelos.ts index d297f0d52..fa402285b 100644 --- a/core/renderers/zelos/zelos.ts +++ b/core/renderers/zelos/zelos.ts @@ -1,4 +1,4 @@ -/** @fileoverview Re-exports of Blockly.zelos.* modules. */ +/** @file Re-exports of Blockly.zelos.* modules. */ /** * @license @@ -8,6 +8,7 @@ /** * Re-exports of Blockly.zelos.* modules. + * * @namespace Blockly.zelos */ import * as goog from '../../../closure/goog/goog.js'; diff --git a/core/scrollbar.ts b/core/scrollbar.ts index e32a35cb2..8a117cb41 100644 --- a/core/scrollbar.ts +++ b/core/scrollbar.ts @@ -6,6 +6,7 @@ /** * Object representing a scrollbar. + * * @class */ import * as goog from '../closure/goog/goog.js'; @@ -30,6 +31,7 @@ import type {WorkspaceSvg} from './workspace_svg.js'; * Class for a pure SVG scrollbar. * This technique offers a scrollbar that is guaranteed to work, but may not * look or behave like the system's scrollbars. + * * @alias Blockly.Scrollbar */ export class Scrollbar { @@ -42,6 +44,7 @@ export class Scrollbar { /** * Default margin around the scrollbar (between the scrollbar and the edge of * the viewport in pixels). + * * @internal */ static readonly DEFAULT_SCROLLBAR_MARGIN = 0.5; @@ -53,6 +56,7 @@ export class Scrollbar { /** * The ratio of handle position offset to workspace content displacement. + * * @internal */ ratio = 1; @@ -138,6 +142,7 @@ export class Scrollbar { * The upper left corner of the scrollbar's SVG group in CSS pixels relative * to the scrollbar's origin. This is usually relative to the injection div * origin. + * * @internal */ this.position = new Coordinate(0, 0); @@ -179,6 +184,7 @@ export class Scrollbar { /** * Dispose of this scrollbar. * Unlink from all DOM elements to prevent memory leaks. + * * @suppress {checkTypes} */ dispose() { @@ -204,8 +210,9 @@ export class Scrollbar { /** * Constrain the handle's length within the minimum (0) and maximum * (scrollbar background) values allowed for the scrollbar. + * * @param value Value that is potentially out of bounds, in CSS pixels. - * @return Constrained value, in CSS pixels. + * @returns Constrained value, in CSS pixels. */ private constrainHandleLength_(value: number): number { if (value <= 0 || isNaN(value)) { @@ -219,6 +226,7 @@ export class Scrollbar { /** * Set the length of the scrollbar's handle and change the SVG attribute * accordingly. + * * @param newLength The new scrollbar handle length in CSS pixels. */ private setHandleLength_(newLength: number) { @@ -232,8 +240,9 @@ export class Scrollbar { /** * Constrain the handle's position within the minimum (0) and maximum values * allowed for the scrollbar. + * * @param value Value that is potentially out of bounds, in CSS pixels. - * @return Constrained value, in CSS pixels. + * @returns Constrained value, in CSS pixels. */ private constrainHandlePosition_(value: number): number { if (value <= 0 || isNaN(value)) { @@ -250,6 +259,7 @@ export class Scrollbar { /** * Set the offset of the scrollbar's handle from the scrollbar's position, and * change the SVG attribute accordingly. + * * @param newPosition The new scrollbar handle offset in CSS pixels. */ setHandlePosition(newPosition: number) { @@ -263,6 +273,7 @@ export class Scrollbar { /** * Set the size of the scrollbar's background and change the SVG attribute * accordingly. + * * @param newSize The new scrollbar background length in CSS pixels. */ private setScrollbarLength_(newSize: number) { @@ -281,6 +292,7 @@ export class Scrollbar { * Set the position of the scrollbar's SVG group in CSS pixels relative to the * scrollbar's origin. This sets the scrollbar's location within the * workspace. + * * @param x The new x coordinate. * @param y The new y coordinate. * @internal @@ -297,6 +309,7 @@ export class Scrollbar { /** * Recalculate the scrollbar's location and its length. + * * @param opt_metrics A data structure of from the describing all the required * dimensions. If not provided, it will be fetched from the host object. */ @@ -331,9 +344,10 @@ export class Scrollbar { /** * Returns whether the a resizeView is necessary by comparing the passed * hostMetrics with cached old host metrics. + * * @param hostMetrics A data structure describing all the required dimensions, * possibly fetched from the host object. - * @return Whether a resizeView is necessary. + * @returns Whether a resizeView is necessary. */ private requiresViewResize_(hostMetrics: Metrics): boolean { if (!this.oldHostMetrics_) { @@ -347,6 +361,7 @@ export class Scrollbar { /** * Recalculate a horizontal scrollbar's location and length. + * * @param hostMetrics A data structure describing all the required dimensions, * possibly fetched from the host object. */ @@ -362,6 +377,7 @@ export class Scrollbar { * Recalculate a horizontal scrollbar's location on the screen and path * length. This should be called when the layout or size of the window has * changed. + * * @param hostMetrics A data structure describing all the required dimensions, * possibly fetched from the host object. */ @@ -392,6 +408,7 @@ export class Scrollbar { /** * Recalculate a horizontal scrollbar's location within its path and length. * This should be called when the contents of the workspace have changed. + * * @param hostMetrics A data structure describing all the required dimensions, * possibly fetched from the host object. */ @@ -445,6 +462,7 @@ export class Scrollbar { /** * Recalculate a vertical scrollbar's location and length. + * * @param hostMetrics A data structure describing all the required dimensions, * possibly fetched from the host object. */ @@ -459,6 +477,7 @@ export class Scrollbar { /** * Recalculate a vertical scrollbar's location on the screen and path length. * This should be called when the layout or size of the window has changed. + * * @param hostMetrics A data structure describing all the required dimensions, * possibly fetched from the host object. */ @@ -486,6 +505,7 @@ export class Scrollbar { /** * Recalculate a vertical scrollbar's location within its path and length. * This should be called when the contents of the workspace have changed. + * * @param hostMetrics A data structure describing all the required dimensions, * possibly fetched from the host object. */ @@ -540,6 +560,7 @@ export class Scrollbar { /** * Create all the DOM elements required for a scrollbar. * The resulting widget is not sized. + * * @param opt_class A class to be applied to this scrollbar. */ private createDom_(opt_class?: string) { @@ -591,7 +612,8 @@ export class Scrollbar { /** * Is the scrollbar visible. Non-paired scrollbars disappear when they aren't * needed. - * @return True if visible. + * + * @returns True if visible. */ isVisible(): boolean { return this.isVisible_; @@ -600,6 +622,7 @@ export class Scrollbar { /** * Set whether the scrollbar's container is visible and update * display accordingly if visibility has changed. + * * @param visible Whether the container is visible */ setContainerVisible(visible: boolean) { @@ -614,6 +637,7 @@ export class Scrollbar { /** * Set whether the scrollbar is visible. * Only applies to non-paired scrollbars. + * * @param visible True if visible. */ setVisible(visible: boolean) { @@ -654,6 +678,7 @@ export class Scrollbar { /** * Scroll by one pageful. * Called when scrollbar background is clicked. + * * @param e Mouse down event. */ private onMouseDownBar_(e: MouseEvent) { @@ -693,6 +718,7 @@ export class Scrollbar { /** * Start a dragging operation. * Called when scrollbar handle is clicked. + * * @param e Mouse down event. */ private onMouseDownHandle_(e: MouseEvent) { @@ -734,6 +760,7 @@ export class Scrollbar { /** * Drag the scrollbar's handle. + * * @param e Mouse up event. */ private onMouseMoveHandle_(e: Event) { @@ -788,7 +815,8 @@ export class Scrollbar { /** * Helper to calculate the ratio of handle position to scrollbar view size. - * @return Ratio. + * + * @returns Ratio. * @internal */ getRatio_(): number { @@ -821,6 +849,7 @@ export class Scrollbar { /** * Set the scrollbar handle's position. + * * @param value The content displacement, relative to the view in pixels. * @param updateMetrics Whether to update metrics on this set call. * Defaults to true. @@ -837,6 +866,7 @@ export class Scrollbar { * relative to the injection div origin. This is for times when the scrollbar * is used in an object whose origin isn't the same as the main workspace * (e.g. in a flyout.) + * * @param x The x coordinate of the scrollbar's origin, in CSS pixels. * @param y The y coordinate of the scrollbar's origin, in CSS pixels. */ @@ -848,7 +878,7 @@ export class Scrollbar { * @param first An object containing computed measurements of a workspace. * @param second Another object containing computed measurements of a * workspace. - * @return Whether the two sets of metrics are equivalent. + * @returns Whether the two sets of metrics are equivalent. */ private static metricsAreEquivalent_(first: Metrics, second: Metrics): boolean { diff --git a/core/scrollbar_pair.ts b/core/scrollbar_pair.ts index b3323ddda..c9420c249 100644 --- a/core/scrollbar_pair.ts +++ b/core/scrollbar_pair.ts @@ -6,6 +6,7 @@ /** * Object representing a pair of scrollbars. + * * @class */ import * as goog from '../closure/goog/goog.js'; @@ -21,6 +22,7 @@ import type {WorkspaceSvg} from './workspace_svg.js'; /** * Class for a pair of scrollbars. Horizontal and vertical. + * * @alias Blockly.ScrollbarPair */ export class ScrollbarPair { @@ -68,6 +70,7 @@ export class ScrollbarPair { /** * Dispose of this pair of scrollbars. * Unlink from all DOM elements to prevent memory leaks. + * * @suppress {checkTypes} */ dispose() { @@ -161,7 +164,8 @@ export class ScrollbarPair { /** * Returns whether scrolling horizontally is enabled. - * @return True if horizontal scroll is enabled. + * + * @returns True if horizontal scroll is enabled. */ canScrollHorizontally(): boolean { return !!this.hScroll; @@ -169,7 +173,8 @@ export class ScrollbarPair { /** * Returns whether scrolling vertically is enabled. - * @return True if vertical scroll is enabled. + * + * @returns True if vertical scroll is enabled. */ canScrollVertically(): boolean { return !!this.vScroll; @@ -180,6 +185,7 @@ export class ScrollbarPair { * relative to the injection div origin. This is for times when the scrollbar * is used in an object whose origin isn't the same as the main workspace * (e.g. in a flyout.) + * * @param x The x coordinate of the scrollbar's origin, in CSS pixels. * @param y The y coordinate of the scrollbar's origin, in CSS pixels. * @internal @@ -195,6 +201,7 @@ export class ScrollbarPair { /** * Set the handles of both scrollbars. + * * @param x The horizontal content displacement, relative to the view in * pixels. * @param y The vertical content displacement, relative to the view in pixels. @@ -237,6 +244,7 @@ export class ScrollbarPair { /** * Set the handle of the horizontal scrollbar to be at a certain position in * CSS pixels relative to its parents. + * * @param x Horizontal scroll value. */ setX(x: number) { @@ -248,6 +256,7 @@ export class ScrollbarPair { /** * Set the handle of the vertical scrollbar to be at a certain position in * CSS pixels relative to its parents. + * * @param y Vertical scroll value. */ setY(y: number) { @@ -258,6 +267,7 @@ export class ScrollbarPair { /** * Set whether this scrollbar's container is visible. + * * @param visible Whether the container is visible. */ setContainerVisible(visible: boolean) { @@ -272,7 +282,8 @@ export class ScrollbarPair { /** * If any of the scrollbars are visible. Non-paired scrollbars may disappear * when they aren't needed. - * @return True if visible. + * + * @returns True if visible. */ isVisible(): boolean { let isVisible = false; @@ -288,6 +299,7 @@ export class ScrollbarPair { /** * Recalculates the scrollbars' locations within their path and length. * This should be called when the contents of the workspace have changed. + * * @param hostMetrics A data structure describing all the required dimensions, * possibly fetched from the host object. */ @@ -303,6 +315,7 @@ export class ScrollbarPair { /** * Recalculates the scrollbars' locations on the screen and path length. * This should be called when the layout or size of the window has changed. + * * @param hostMetrics A data structure describing all the required dimensions, * possibly fetched from the host object. */ diff --git a/core/serialization/blocks.ts b/core/serialization/blocks.ts index 8d357eabd..fbe9ca9e0 100644 --- a/core/serialization/blocks.ts +++ b/core/serialization/blocks.ts @@ -6,6 +6,7 @@ /** * Handles serializing blocks to plain JavaScript objects only containing state. + * * @namespace Blockly.serialization.blocks */ import * as goog from '../../closure/goog/goog.js'; @@ -31,6 +32,7 @@ import * as serializationRegistry from './registry.js'; /** * Represents the state of a connection. + * * @alias Blockly.serialization.blocks.ConnectionState */ export interface ConnectionState { @@ -40,6 +42,7 @@ export interface ConnectionState { /** * Represents the state of a given block. + * * @alias Blockly.serialization.blocks.State */ export interface State { @@ -60,6 +63,7 @@ export interface State { /** * Returns the state of the given block as a plain JavaScript object. + * * @param block The block to serialize. * @param param1 addCoordinates: If true, the coordinates of the block are added * to the serialized state. False by default. addinputBlocks: If true, @@ -71,7 +75,11 @@ export interface State { * instead serialize all of the info about that state. This supports * deserializing the block into a workspace where that state doesn't yet * exist. True by default. - * @return The serialized state of the block, or null if the block could not be + * @param param1.addCoordinates + * @param param1.addInputBlocks + * @param param1.addNextBlocks + * @param param1.doFullSerialization + * @returns The serialized state of the block, or null if the block could not be * serialied (eg it was an insertion marker). * @alias Blockly.serialization.blocks.save */ @@ -131,6 +139,7 @@ export function save(block: Block, { /** * Adds attributes to the given state object based on the state of the block. * Eg collapsed, disabled, inline, etc. + * * @param block The block to base the attributes on. * @param state The state object to append to. */ @@ -153,6 +162,7 @@ function saveAttributes(block: Block, state: State) { /** * Adds the coordinates of the given block to the given state object. + * * @param block The block to base the coordinates on. * @param state The state object to append to. */ @@ -164,6 +174,7 @@ function saveCoords(block: Block, state: State) { } /** * Adds any extra state the block may provide to the given state object. + * * @param block The block to serialize the extra state of. * @param state The state object to append to. */ @@ -186,6 +197,7 @@ function saveExtraState(block: Block, state: State) { /** * Adds the state of all of the icons on the block to the given state object. + * * @param block The block to serialize the icon state of. * @param state The state object to append to. */ @@ -205,6 +217,7 @@ function saveIcons(block: Block, state: State) { /** * Adds the state of all of the fields on the block to the given state object. + * * @param block The block to serialize the field state of. * @param state The state object to append to. * @param doFullSerialization Whether or not to serialize the full state of the @@ -229,6 +242,7 @@ function saveFields(block: Block, state: State, doFullSerialization: boolean) { /** * Adds the state of all of the child blocks of the given block (which are * connected to inputs) to the given state object. + * * @param block The block to serialize the input blocks of. * @param state The state object to append to. * @param doFullSerialization Whether or not to do full serialization. @@ -256,6 +270,7 @@ function saveInputBlocks( /** * Adds the state of all of the next blocks of the given block to the given * state object. + * * @param block The block to serialize the next blocks of. * @param state The state object to append to. * @param doFullSerialization Whether or not to do full serialization. @@ -275,8 +290,9 @@ function saveNextBlocks( /** * Returns the state of the given connection (ie the state of any connected * shadow or real blocks). + * * @param connection The connection to serialize the connected blocks of. - * @return An object containing the state of any connected shadow block, or any + * @returns An object containing the state of any connected shadow block, or any * connected real block. * @param doFullSerialization Whether or not to do full serialization. */ @@ -299,11 +315,13 @@ function saveConnection(connection: Connection, doFullSerialization: boolean): /** * Loads the block represented by the given state into the given workspace. + * * @param state The state of a block to deserialize into the workspace. * @param workspace The workspace to add the block to. * @param param1 recordUndo: If true, events triggered by this function will be * undo-able by the user. False by default. - * @return The block that was just loaded. + * @param param1.recordUndo + * @returns The block that was just loaded. * @alias Blockly.serialization.blocks.append */ export function append( @@ -318,6 +336,7 @@ export function append( * external API. * But it is exported so that other places within Blockly can call it directly * with the extra parameters. + * * @param state The state of a block to deserialize into the workspace. * @param workspace The workspace to add the block to. * @param param1 parentConnection: If provided, the system will attempt to @@ -325,7 +344,10 @@ export function append( * default. isShadow: If true, the block will be set to a shadow block after * it is created. False by default. recordUndo: If true, events triggered by * this function will be undo-able by the user. False by default. - * @return The block that was just appended. + * @param param1.parentConnection + * @param param1.isShadow + * @param param1.recordUndo + * @returns The block that was just appended. * @alias Blockly.serialization.blocks.appendInternal * @internal */ @@ -370,13 +392,16 @@ export function appendInternal( * This is defined privately so that it can be called recursively without firing * eroneous events. Events (and other things we only want to occur on the top * block) are handled by appendInternal. + * * @param state The state of a block to deserialize into the workspace. * @param workspace The workspace to add the block to. * @param param1 parentConnection: If provided, the system will attempt to * connect the block to this connection after it is created. Undefined by * default. isShadow: The block will be set to a shadow block after it is * created. False by default. - * @return The block that was just appended. + * @param param1.parentConnection + * @param param1.isShadow + * @returns The block that was just appended. */ function appendPrivate( state: State, workspace: Workspace, @@ -404,6 +429,7 @@ function appendPrivate( /** * Applies any coordinate information available on the state object to the * block. + * * @param block The block to set the position of. * @param state The state object to reference. */ @@ -419,6 +445,7 @@ function loadCoords(block: Block, state: State) { /** * Applies any attribute information available on the state object to the block. + * * @param block The block to set the attributes of. * @param state The state object to reference. */ @@ -440,6 +467,7 @@ function loadAttributes(block: Block, state: State) { /** * Applies any extra state information available on the state object to the * block. + * * @param block The block to set the extra state of. * @param state The state object to reference. */ @@ -456,6 +484,7 @@ function loadExtraState(block: Block, state: State) { /** * Attempts to connect the block to the parent connection, if it exists. + * * @param parentConnection The parent connection to try to connect the block to. * @param child The block to try to connect to the parent. * @param state The state which defines the given block @@ -502,6 +531,7 @@ function tryToConnectParent( /** * Applies icon state to the icons on the block, based on the given state * object. + * * @param block The block to set the icon state of. * @param state The state object to reference. */ @@ -530,6 +560,7 @@ function loadIcons(block: Block, state: State) { /** * Applies any field information available on the state object to the block. + * * @param block The block to set the field state of. * @param state The state object to reference. */ @@ -554,6 +585,7 @@ function loadFields(block: Block, state: State) { /** * Creates any child blocks (attached to inputs) defined by the given state * and attaches them to the given block. + * * @param block The block to attach input blocks to. * @param state The state object to reference. */ @@ -575,6 +607,7 @@ function loadInputBlocks(block: Block, state: State) { /** * Creates any next blocks defined by the given state and attaches them to the * given block. + * * @param block The block to attach next blocks to. * @param state The state object to reference. */ @@ -590,6 +623,7 @@ function loadNextBlocks(block: Block, state: State) { /** * Applies the state defined by connectionState to the given connection, ie * assigns shadows and attaches child blocks. + * * @param connection The connection to deserialize the connected blocks of. * @param connectionState The object containing the state of any connected * shadow block, or any connected real block. @@ -609,6 +643,7 @@ function loadConnection( // TODO(#5146): Remove this from the serialization system. /** * Initializes the give block, eg init the model, inits the svg, renders, etc. + * * @param block The block to initialize. * @param rendered Whether the block is a rendered or headless block. */ @@ -637,6 +672,7 @@ const saveBlock = save; /** * Serializer for saving and loading block state. + * * @alias Blockly.serialization.blocks.BlockSerializer */ class BlockSerializer implements ISerializer { @@ -650,8 +686,9 @@ class BlockSerializer implements ISerializer { /** * Serializes the blocks of the given workspace. + * * @param workspace The workspace to save the blocks of. - * @return The state of the workspace's blocks, or null if there are no + * @returns The state of the workspace's blocks, or null if there are no * blocks. */ save(workspace: Workspace): {languageVersion: number, blocks: State[]}|null { @@ -675,8 +712,11 @@ class BlockSerializer implements ISerializer { /** * Deserializes the blocks defined by the given state into the given * workspace. + * * @param state The state of the blocks to deserialize. + * @param state.languageVersion * @param workspace The workspace to deserialize into. + * @param state.blocks */ load( state: {languageVersion: number, blocks: State[]}, workspace: Workspace) { @@ -688,6 +728,7 @@ class BlockSerializer implements ISerializer { /** * Disposes of any blocks that exist on the workspace. + * * @param workspace The workspace to clear the blocks of. */ clear(workspace: Workspace) { diff --git a/core/serialization/exceptions.ts b/core/serialization/exceptions.ts index a1c462299..440769450 100644 --- a/core/serialization/exceptions.ts +++ b/core/serialization/exceptions.ts @@ -6,6 +6,7 @@ /** * Contains custom errors thrown by the serialization system. + * * @namespace Blockly.serialization.exceptions */ import * as goog from '../../closure/goog/goog.js'; @@ -21,6 +22,7 @@ export class DeserializationError extends Error {} /** * Represents an error where the serialized state is expected to provide a * block type, but it is not provided. + * * @alias Blockly.serialization.exceptions.MissingBlockType */ export class MissingBlockType extends DeserializationError { @@ -36,6 +38,7 @@ export class MissingBlockType extends DeserializationError { /** * Represents an error where deserialization encountered a block that did * not have a connection that was defined in the serialized state. + * * @alias Blockly.serialization.exceptions.MissingConnection */ export class MissingConnection extends DeserializationError { @@ -55,6 +58,7 @@ connection`); /** * Represents an error where deserialization tried to connect two connections * that were not compatible. + * * @alias Blockly.serialization.exceptions.BadConnectionCheck */ export class BadConnectionCheck extends DeserializationError { @@ -79,6 +83,7 @@ ${childConnection} to its parent, because: ${reason}`); * was deserializing children of a shadow. * This is an error because it is an invariant of Blockly that shadow blocks * do not have real children. + * * @alias Blockly.serialization.exceptions.RealChildOfShadow */ export class RealChildOfShadow extends DeserializationError { diff --git a/core/serialization/priorities.ts b/core/serialization/priorities.ts index 5ebeee690..b8c8f2613 100644 --- a/core/serialization/priorities.ts +++ b/core/serialization/priorities.ts @@ -8,6 +8,7 @@ * The top level namespace for priorities of plugin serializers. * Includes constants for the priorities of different plugin serializers. Higher * priorities are deserialized first. + * * @namespace Blockly.serialization.priorities */ import * as goog from '../../closure/goog/goog.js'; @@ -16,11 +17,13 @@ goog.declareModuleId('Blockly.serialization.priorities'); /** * The priority for deserializing variables. + * * @alias Blockly.serialization.priorities.VARIABLES */ export const VARIABLES = 100; /** * The priority for deserializing blocks. + * * @alias Blockly.serialization.priorities.BLOCKS */ export const BLOCKS = 50; diff --git a/core/serialization/registry.ts b/core/serialization/registry.ts index cd87b1930..ab6b2023c 100644 --- a/core/serialization/registry.ts +++ b/core/serialization/registry.ts @@ -7,6 +7,7 @@ /** * Contains functions registering serializers (eg blocks, variables, plugins, * etc). + * * @namespace Blockly.serialization.registry */ import * as goog from '../../closure/goog/goog.js'; @@ -20,6 +21,7 @@ import * as registry from '../registry.js'; /** * Registers the given serializer so that it can be used for serialization and * deserialization. + * * @param name The name of the serializer to register. * @param serializer The serializer to register. * @alias Blockly.serialization.registry.register @@ -30,6 +32,7 @@ export function register(name: string, serializer: ISerializer) { /** * Unregisters the serializer associated with the given name. + * * @param name The name of the serializer to unregister. * @alias Blockly.serialization.registry.unregister */ diff --git a/core/serialization/variables.ts b/core/serialization/variables.ts index 19cef5bea..5fac0097e 100644 --- a/core/serialization/variables.ts +++ b/core/serialization/variables.ts @@ -7,6 +7,7 @@ /** * Handles serializing variables to plain JavaScript objects, only containing * state. + * * @namespace Blockly.serialization.variables */ import * as goog from '../../closure/goog/goog.js'; @@ -21,6 +22,7 @@ import * as serializationRegistry from './registry.js'; /** * Represents the state of a given variable. + * * @alias Blockly.serialization.variables.State */ export interface State { @@ -31,6 +33,7 @@ export interface State { /** * Serializer for saving and loading variable state. + * * @alias Blockly.serialization.variables.VariableSerializer */ class VariableSerializer implements ISerializer { @@ -44,8 +47,9 @@ class VariableSerializer implements ISerializer { /** * Serializes the variables of the given workspace. + * * @param workspace The workspace to save the variables of. - * @return The state of the workspace's variables, or null if there are no + * @returns The state of the workspace's variables, or null if there are no * variables. */ save(workspace: Workspace): State[]|null { @@ -69,6 +73,7 @@ class VariableSerializer implements ISerializer { /** * Deserializes the variable defined by the given state into the given * workspace. + * * @param state The state of the variables to deserialize. * @param workspace The workspace to deserialize into. */ @@ -81,6 +86,7 @@ class VariableSerializer implements ISerializer { /** * Disposes of any variables that exist on the workspace. + * * @param workspace The workspace to clear the variables of. */ clear(workspace: Workspace) { diff --git a/core/serialization/workspaces.ts b/core/serialization/workspaces.ts index d561397e5..0cf19e6e5 100644 --- a/core/serialization/workspaces.ts +++ b/core/serialization/workspaces.ts @@ -7,6 +7,7 @@ /** * Contains top-level functions for serializing workspaces to plain JavaScript * objects. + * * @namespace Blockly.serialization.workspaces */ import * as goog from '../../closure/goog/goog.js'; @@ -23,8 +24,9 @@ import {WorkspaceSvg} from '../workspace_svg.js'; /** * Returns the state of the workspace as a plain JavaScript object. + * * @param workspace The workspace to serialize. - * @return The serialized state of the workspace. + * @returns The serialized state of the workspace. * @alias Blockly.serialization.workspaces.save */ export function save(workspace: Workspace): @@ -42,10 +44,12 @@ export function save(workspace: Workspace): /** * Loads the variable represented by the given state into the given workspace. + * * @param state The state of the workspace to deserialize into the workspace. * @param workspace The workspace to add the new state to. * @param param1 recordUndo: If true, events triggered by this function will be * undo-able by the user. False by default. + * @param param1.recordUndo * @alias Blockly.serialization.workspaces.load */ export function load( diff --git a/core/shortcut_items.ts b/core/shortcut_items.ts index c9d364945..707a252f6 100644 --- a/core/shortcut_items.ts +++ b/core/shortcut_items.ts @@ -6,6 +6,7 @@ /** * Registers default keyboard shortcuts. + * * @namespace Blockly.ShortcutItems */ import * as goog from '../closure/goog/goog.js'; @@ -23,6 +24,7 @@ import type {WorkspaceSvg} from './workspace_svg.js'; /** * Object holding the names of the default shortcut items. + * * @alias Blockly.ShortcutItems.names */ export enum names { @@ -37,6 +39,7 @@ export enum names { /** * Keyboard shortcut to hide chaff on escape. + * * @alias Blockly.ShortcutItems.registerEscape */ export function registerEscape() { @@ -58,6 +61,7 @@ export function registerEscape() { /** * Keyboard shortcut to delete a block on delete or backspace + * * @alias Blockly.ShortcutItems.registerDelete */ export function registerDelete() { @@ -88,6 +92,7 @@ export function registerDelete() { /** * Keyboard shortcut to copy a block on ctrl+c, cmd+c, or alt+c. + * * @alias Blockly.ShortcutItems.registerCopy */ export function registerCopy() { @@ -122,6 +127,7 @@ export function registerCopy() { /** * Keyboard shortcut to copy and delete a block on ctrl+x, cmd+x, or alt+x. + * * @alias Blockly.ShortcutItems.registerCut */ export function registerCut() { @@ -159,6 +165,7 @@ export function registerCut() { /** * Keyboard shortcut to paste a block on ctrl+v, cmd+v, or alt+v. + * * @alias Blockly.ShortcutItems.registerPaste */ export function registerPaste() { @@ -185,6 +192,7 @@ export function registerPaste() { /** * Keyboard shortcut to undo the previous action on ctrl+z, cmd+z, or alt+z. + * * @alias Blockly.ShortcutItems.registerUndo */ export function registerUndo() { @@ -214,6 +222,7 @@ export function registerUndo() { /** * Keyboard shortcut to redo the previous action on ctrl+shift+z, cmd+shift+z, * or alt+shift+z. + * * @alias Blockly.ShortcutItems.registerRedo */ export function registerRedo() { @@ -246,6 +255,7 @@ export function registerRedo() { /** * Registers all default keyboard shortcut item. This should be called once per * instance of KeyboardShortcutRegistry. + * * @alias Blockly.ShortcutItems.registerDefaultShortcuts * @internal */ diff --git a/core/shortcut_registry.ts b/core/shortcut_registry.ts index b48ef416a..795a57c73 100644 --- a/core/shortcut_registry.ts +++ b/core/shortcut_registry.ts @@ -7,6 +7,7 @@ /** * The namespace used to keep track of keyboard shortcuts and the * key codes used to execute those shortcuts. + * * @class */ import * as goog from '../closure/goog/goog.js'; @@ -21,6 +22,7 @@ import type {Workspace} from './workspace.js'; * Class for the registry of keyboard shortcuts. This is intended to be a * singleton. You should not create a new instance, and only access this class * from ShortcutRegistry.registry. + * * @alias Blockly.ShortcutRegistry */ export class ShortcutRegistry { @@ -45,6 +47,7 @@ export class ShortcutRegistry { /** * Registers a keyboard shortcut. + * * @param shortcut The shortcut for this key code. * @param opt_allowOverrides True to prevent a warning when overriding an * already registered item. @@ -70,8 +73,9 @@ export class ShortcutRegistry { /** * Unregisters a keyboard shortcut registered with the given key code. This * will also remove any key mappings that reference this shortcut. + * * @param shortcutName The name of the shortcut to unregister. - * @return True if an item was unregistered, false otherwise. + * @returns True if an item was unregistered, false otherwise. */ unregister(shortcutName: string): boolean { const shortcut = this.shortcuts.get(shortcutName); @@ -90,6 +94,7 @@ export class ShortcutRegistry { /** * Adds a mapping between a keycode and a keyboard shortcut. + * * @param keyCode The key code for the keyboard shortcut. If registering a key * code with a modifier (ex: ctrl+c) use * ShortcutRegistry.registry.createSerializedKey; @@ -117,6 +122,7 @@ export class ShortcutRegistry { /** * Removes a mapping between a keycode and a keyboard shortcut. + * * @param keyCode The key code for the keyboard shortcut. If registering a key * code with a modifier (ex: ctrl+c) use * ShortcutRegistry.registry.createSerializedKey; @@ -124,7 +130,7 @@ export class ShortcutRegistry { * keycode is pressed. * @param opt_quiet True to not console warn when there is no shortcut to * remove. - * @return True if a key mapping was removed, false otherwise. + * @returns True if a key mapping was removed, false otherwise. */ removeKeyMapping(keyCode: string, shortcutName: string, opt_quiet?: boolean): boolean { @@ -159,6 +165,7 @@ export class ShortcutRegistry { * Removes all the key mappings for a shortcut with the given name. * Useful when changing the default key mappings and the key codes registered * to the shortcut are unknown. + * * @param shortcutName The name of the shortcut to remove from the key map. */ removeAllKeyMappings(shortcutName: string) { @@ -170,6 +177,7 @@ export class ShortcutRegistry { /** * Sets the key map. Setting the key map will override any default key * mappings. + * * @param newKeyMap The object with key code to shortcut names. */ setKeyMap(newKeyMap: {[key: string]: string[]}) { @@ -181,7 +189,8 @@ export class ShortcutRegistry { /** * Gets the current key map. - * @return The object holding key codes to ShortcutRegistry.KeyboardShortcut. + * + * @returns The object holding key codes to ShortcutRegistry.KeyboardShortcut. */ getKeyMap(): {[key: string]: string[]} { const legacyKeyMap: {[key: string]: string[]} = Object.create(null); @@ -193,7 +202,8 @@ export class ShortcutRegistry { /** * Gets the registry of keyboard shortcuts. - * @return The registry of keyboard shortcuts. + * + * @returns The registry of keyboard shortcuts. */ getRegistry(): {[key: string]: KeyboardShortcut} { const legacyRegistry: {[key: string]: KeyboardShortcut} = @@ -206,9 +216,10 @@ export class ShortcutRegistry { /** * Handles key down events. + * * @param workspace The main workspace where the event was captured. * @param e The key down event. - * @return True if the event was handled, false otherwise. + * @returns True if the event was handled, false otherwise. */ onKeyDown(workspace: Workspace, e: KeyboardEvent): boolean { const key = this.serializeKeyEvent_(e); @@ -230,8 +241,9 @@ export class ShortcutRegistry { /** * Gets the shortcuts registered to the given key code. + * * @param keyCode The serialized key code. - * @return The list of shortcuts to call when the given keyCode is used. + * @returns The list of shortcuts to call when the given keyCode is used. * Undefined if no shortcuts exist. */ getShortcutNamesByKeyCode(keyCode: string): string[]|undefined { @@ -241,8 +253,9 @@ export class ShortcutRegistry { /** * Gets the serialized key codes that the shortcut with the given name is * registered under. + * * @param shortcutName The name of the shortcut. - * @return An array with all the key codes the shortcut is registered under. + * @returns An array with all the key codes the shortcut is registered under. */ getKeyCodesByShortcutName(shortcutName: string): string[] { const keys = []; @@ -257,8 +270,9 @@ export class ShortcutRegistry { /** * Serializes a key event. + * * @param e A key down event. - * @return The serialized key code for the given event. + * @returns The serialized key code for the given event. */ private serializeKeyEvent_(e: KeyboardEvent): string { let serializedKey = ''; @@ -280,6 +294,7 @@ export class ShortcutRegistry { /** * Checks whether any of the given modifiers are not valid. + * * @param modifiers List of modifiers to be used with the key. * @throws {Error} if the modifier is not in the valid modifiers list. */ @@ -294,10 +309,11 @@ export class ShortcutRegistry { /** * Creates the serialized key code that will be used in the key map. + * * @param keyCode Number code representing the key. * @param modifiers List of modifier key codes to be used with the key. All * valid modifiers can be found in the ShortcutRegistry.modifierKeys. - * @return The serialized key code for the given modifiers and key. + * @returns The serialized key code for the given modifiers and key. */ createSerializedKey(keyCode: number, modifiers: KeyCodes[]|null): string { let serializedKey = ''; diff --git a/core/sprites.ts b/core/sprites.ts index da4bf1958..223535ca9 100644 --- a/core/sprites.ts +++ b/core/sprites.ts @@ -7,6 +7,7 @@ /** * Contains the path to a single png tat holds the images for the trashcan * as well as the zoom controls. + * * @alias Blockly.sprite.SPRITE */ export const SPRITE = { diff --git a/core/theme/classic.ts b/core/theme/classic.ts index 367504da7..8989573ab 100644 --- a/core/theme/classic.ts +++ b/core/theme/classic.ts @@ -7,6 +7,7 @@ /** * Classic theme. * Contains multi-coloured border to create shadow effect. + * * @namespace Blockly.Themes.Classic */ import * as goog from '../../closure/goog/goog.js'; @@ -43,6 +44,7 @@ const categoryStyles = { /** * Classic theme. * Contains multi-coloured border to create shadow effect. + * * @alias Blockly.Themes.Classic */ export const Classic = new Theme( diff --git a/core/theme/zelos.ts b/core/theme/zelos.ts index 6b7c3cefd..a0583cd69 100644 --- a/core/theme/zelos.ts +++ b/core/theme/zelos.ts @@ -6,6 +6,7 @@ /** * Zelos theme. + * * @namespace Blockly.Themes.Zelos */ import * as goog from '../../closure/goog/goog.js'; @@ -82,6 +83,7 @@ const categoryStyles = { /** * Zelos theme. + * * @alias Blockly.Themes.Zelos */ export const Zelos = new Theme('zelos', defaultBlockStyles, categoryStyles); diff --git a/core/theme_manager.ts b/core/theme_manager.ts index 6c90d05b7..8630f13fd 100644 --- a/core/theme_manager.ts +++ b/core/theme_manager.ts @@ -7,6 +7,7 @@ /** * Object in charge of storing and updating a workspace theme * and UI components. + * * @class */ import * as goog from '../closure/goog/goog.js'; @@ -21,6 +22,7 @@ import type {WorkspaceSvg} from './workspace_svg.js'; /** * Class for storing and updating a workspace's theme and UI components. + * * @alias Blockly.ThemeManager */ export class ThemeManager { @@ -38,7 +40,8 @@ export class ThemeManager { /** * Get the workspace theme. - * @return The workspace theme. + * + * @returns The workspace theme. * @internal */ getTheme(): Theme { @@ -47,6 +50,7 @@ export class ThemeManager { /** * Set the workspace theme, and refresh the workspace and all components. + * * @param theme The workspace theme. * @internal */ @@ -87,6 +91,7 @@ export class ThemeManager { /** * Subscribe a workspace to changes to the selected theme. If a new theme is * set, the workspace is called to refresh its blocks. + * * @param workspace The workspace to subscribe. * @internal */ @@ -96,6 +101,7 @@ export class ThemeManager { /** * Unsubscribe a workspace to changes to the selected theme. + * * @param workspace The workspace to unsubscribe. * @internal */ @@ -109,6 +115,7 @@ export class ThemeManager { /** * Subscribe an element to changes to the selected theme. If a new theme is * selected, the element's style is refreshed with the new theme's style. + * * @param element The element to subscribe. * @param componentName The name used to identify the component. This must be * the same name used to configure the style in the Theme object. @@ -132,6 +139,7 @@ export class ThemeManager { /** * Unsubscribe an element to changes to the selected theme. + * * @param element The element to unsubscribe. * @internal */ @@ -155,6 +163,7 @@ export class ThemeManager { /** * Dispose of this theme manager. + * * @suppress {checkTypes} * @internal */ diff --git a/core/toolbox/category.ts b/core/toolbox/category.ts index 2b4dbe9b5..3b9594113 100644 --- a/core/toolbox/category.ts +++ b/core/toolbox/category.ts @@ -6,6 +6,7 @@ /** * A toolbox category used to organize blocks in the toolbox. + * * @class */ import * as goog from '../../closure/goog/goog.js'; @@ -28,6 +29,7 @@ import {ToolboxItem} from './toolbox_item.js'; /** * Class for a category in a toolbox. + * * @alias Blockly.ToolboxCategory */ export class ToolboxCategory extends ToolboxItem implements @@ -115,7 +117,8 @@ export class ToolboxCategory extends ToolboxItem implements /** * Creates an object holding the default classes for a category. - * @return The configuration object holding all the CSS classes for a + * + * @returns The configuration object holding all the CSS classes for a * category. */ protected makeDefaultCssConfig_(): CssConfig { @@ -139,6 +142,7 @@ export class ToolboxCategory extends ToolboxItem implements /** * Parses the contents array depending on if the category is a dynamic * category, or if its contents are meant to be shown in the flyout. + * * @param categoryDef The information needed to create a category. */ protected parseContents_(categoryDef: toolbox.CategoryInfo) { @@ -159,6 +163,7 @@ export class ToolboxCategory extends ToolboxItem implements /** * Parses the non-contents parts of the category def. + * * @param categoryDef The information needed to create a category. */ protected parseCategoryDef_(categoryDef: toolbox.CategoryInfo) { @@ -173,7 +178,8 @@ export class ToolboxCategory extends ToolboxItem implements /** * Creates the DOM for the category. - * @return The parent element for the category. + * + * @returns The parent element for the category. */ protected createDom_(): HTMLDivElement { this.htmlDiv_ = this.createContainer_(); @@ -208,7 +214,8 @@ export class ToolboxCategory extends ToolboxItem implements /** * Creates the container that holds the row and any subcategories. - * @return The div that holds the icon and the label. + * + * @returns The div that holds the icon and the label. */ protected createContainer_(): HTMLDivElement { const container = (document.createElement('div')); @@ -222,7 +229,8 @@ export class ToolboxCategory extends ToolboxItem implements /** * Creates the parent of the contents container. All clicks will happen on * this div. - * @return The div that holds the contents container. + * + * @returns The div that holds the contents container. */ protected createRowContainer_(): HTMLDivElement { const rowDiv = (document.createElement('div')); @@ -245,7 +253,8 @@ export class ToolboxCategory extends ToolboxItem implements /** * Creates the container for the label and icon. * This is necessary so we can set all subcategory pointer events to none. - * @return The div that holds the icon and the label. + * + * @returns The div that holds the icon and the label. */ protected createRowContentsContainer_(): HTMLDivElement { const contentsContainer = (document.createElement('div')); @@ -259,7 +268,8 @@ export class ToolboxCategory extends ToolboxItem implements /** * Creates the span that holds the category icon. - * @return The span that holds the category icon. + * + * @returns The span that holds the category icon. */ protected createIconDom_(): Element { const toolboxIcon = document.createElement('span'); @@ -277,8 +287,9 @@ export class ToolboxCategory extends ToolboxItem implements /** * Creates the span that holds the category label. * This should have an ID for accessibility purposes. + * * @param name The name of the category. - * @return The span that holds the category label. + * @returns The span that holds the category label. */ protected createLabelDom_(name: string): Element { const toolboxLabel = document.createElement('span'); @@ -299,6 +310,7 @@ export class ToolboxCategory extends ToolboxItem implements /** * Add the strip of colour to the toolbox category. + * * @param colour The category colour. */ protected addColourBorder_(colour: string) { @@ -315,8 +327,9 @@ export class ToolboxCategory extends ToolboxItem implements /** * Gets either the colour or the style for a category. + * * @param categoryDef The object holding information on the category. - * @return The hex colour for the category. + * @returns The hex colour for the category. */ protected getColour_(categoryDef: toolbox.CategoryInfo): string { const styleName = @@ -340,8 +353,9 @@ export class ToolboxCategory extends ToolboxItem implements /** * Sets the colour for the category using the style name and returns the new * colour as a hex string. + * * @param styleName Name of the style. - * @return The hex colour for the category. + * @returns The hex colour for the category. */ private getColourfromStyle_(styleName: string): string { const theme = this.workspace_.getTheme(); @@ -362,7 +376,8 @@ export class ToolboxCategory extends ToolboxItem implements * The parent toolbox element receives clicks. The parent toolbox will add an * ID to this element so it can pass the onClick event to the correct * toolboxItem. - * @return The HTML element that receives clicks. + * + * @returns The HTML element that receives clicks. */ override getClickTarget(): Element { return this.rowDiv_ as Element; @@ -370,9 +385,10 @@ export class ToolboxCategory extends ToolboxItem implements /** * Parses the colour on the category. + * * @param colourValue HSV hue value (0 to 360), #RRGGBB string, or a message * reference string pointing to one of those two values. - * @return The hex colour for the category. + * @returns The hex colour for the category. */ private parseColour_(colourValue: number|string): string { // Decode the colour for any potential message references @@ -401,6 +417,7 @@ export class ToolboxCategory extends ToolboxItem implements /** * Adds appropriate classes to display an open icon. + * * @param iconDiv The div that holds the icon. */ protected openIcon_(iconDiv: Element|null) { @@ -418,6 +435,7 @@ export class ToolboxCategory extends ToolboxItem implements /** * Adds appropriate classes to display a closed icon. + * * @param iconDiv The div that holds the icon. */ protected closeIcon_(iconDiv: Element|null) { @@ -437,6 +455,7 @@ export class ToolboxCategory extends ToolboxItem implements /** * Sets whether the category is visible or not. * For a category to be visible its parent category must also be expanded. + * * @param isVisible True if category should be visible. */ override setVisible_(isVisible: boolean) { @@ -465,7 +484,8 @@ export class ToolboxCategory extends ToolboxItem implements * Whether the category is visible. * A category is only visible if all of its ancestors are expanded and * isHidden_ is false. - * @return True if the category is visible, false otherwise. + * + * @returns True if the category is visible, false otherwise. */ isVisible(): boolean { return !this.isHidden_ && this.allAncestorsExpanded_(); @@ -474,7 +494,8 @@ export class ToolboxCategory extends ToolboxItem implements /** * Whether all ancestors of a category (parent and parent's parent, etc.) are * expanded. - * @return True only if every ancestor is expanded + * + * @returns True only if every ancestor is expanded */ protected allAncestorsExpanded_(): boolean { let category: IToolboxItem = this; @@ -493,6 +514,7 @@ export class ToolboxCategory extends ToolboxItem implements /** * Handles when the toolbox item is clicked. + * * @param _e Click event to handle. */ onClick(_e: Event) {} @@ -500,6 +522,7 @@ export class ToolboxCategory extends ToolboxItem implements /** * Sets the current category as selected. + * * @param isSelected True if this category is selected, false otherwise. */ setSelected(isSelected: boolean) { @@ -517,6 +540,7 @@ export class ToolboxCategory extends ToolboxItem implements /** * Sets whether the category is disabled. + * * @param isDisabled True to disable the category, false otherwise. */ setDisabled(isDisabled: boolean) { @@ -530,7 +554,8 @@ export class ToolboxCategory extends ToolboxItem implements /** * Gets the name of the category. Used for emitting events. - * @return The name of the toolbox item. + * + * @returns The name of the toolbox item. */ getName(): string { return this.name_; @@ -547,7 +572,8 @@ export class ToolboxCategory extends ToolboxItem implements /** * Gets the contents of the category. These are items that are meant to be * displayed in the flyout. - * @return The definition of items to be displayed in the flyout. + * + * @returns The definition of items to be displayed in the flyout. */ getContents(): toolbox.FlyoutItemInfoArray|string { return this.flyoutItems_; @@ -557,6 +583,7 @@ export class ToolboxCategory extends ToolboxItem implements * Updates the contents to be displayed in the flyout. * If the flyout is open when the contents are updated, refreshSelection on * the toolbox must also be called. + * * @param contents The contents to be displayed in the flyout. A string can be * supplied to create a dynamic category. */ diff --git a/core/toolbox/collapsible_category.ts b/core/toolbox/collapsible_category.ts index fc0d0d573..069f4335b 100644 --- a/core/toolbox/collapsible_category.ts +++ b/core/toolbox/collapsible_category.ts @@ -6,6 +6,7 @@ /** * A toolbox category used to organize blocks in the toolbox. + * * @class */ import * as goog from '../../closure/goog/goog.js'; @@ -25,6 +26,7 @@ import {ToolboxSeparator} from './separator.js'; /** * Class for a category in a toolbox that can be collapsed. + * * @alias Blockly.CollapsibleToolboxCategory */ export class CollapsibleToolboxCategory extends ToolboxCategory implements @@ -98,6 +100,7 @@ export class CollapsibleToolboxCategory extends ToolboxCategory implements /** * Creates a toolbox item and adds it to the list of toolbox items. + * * @param itemDef The information needed to create a toolbox item. */ private createToolboxItem_(itemDef: toolbox.ToolboxItemInfo) { @@ -151,8 +154,9 @@ export class CollapsibleToolboxCategory extends ToolboxCategory implements /** * Create the DOM for all subcategories. + * * @param subcategories The subcategories. - * @return The div holding all the subcategories. + * @returns The div holding all the subcategories. */ protected createSubCategoriesDom_(subcategories: IToolboxItem[]): HTMLDivElement { @@ -174,6 +178,7 @@ export class CollapsibleToolboxCategory extends ToolboxCategory implements /** * Opens or closes the current category. + * * @param isExpanded True to expand the category, false to close. */ setExpanded(isExpanded: boolean) { @@ -210,7 +215,8 @@ export class CollapsibleToolboxCategory extends ToolboxCategory implements /** * Whether the category is expanded to show its child subcategories. - * @return True if the toolbox item shows its children, false if it is + * + * @returns True if the toolbox item shows its children, false if it is * collapsed. */ isExpanded(): boolean { @@ -236,7 +242,8 @@ export class CollapsibleToolboxCategory extends ToolboxCategory implements /** * Gets any children toolbox items. (ex. Gets the subcategories) - * @return The child toolbox items. + * + * @returns The child toolbox items. */ getChildToolboxItems(): IToolboxItem[] { return this.toolboxItems_; diff --git a/core/toolbox/separator.ts b/core/toolbox/separator.ts index 7eb7c30bb..09f1a46ea 100644 --- a/core/toolbox/separator.ts +++ b/core/toolbox/separator.ts @@ -6,6 +6,7 @@ /** * A separator used for separating toolbox categories. + * * @class */ import * as goog from '../../closure/goog/goog.js'; @@ -23,6 +24,7 @@ import {ToolboxItem} from './toolbox_item.js'; /** * Class for a toolbox separator. This is the thin visual line that appears on * the toolbox. This item is not interactable. + * * @alias Blockly.ToolboxSeparator */ export class ToolboxSeparator extends ToolboxItem { @@ -52,7 +54,8 @@ export class ToolboxSeparator extends ToolboxItem { /** * Creates the DOM for a separator. - * @return The parent element for the separator. + * + * @returns The parent element for the separator. */ protected createDom_(): HTMLDivElement { const container = (document.createElement('div')); diff --git a/core/toolbox/toolbox.ts b/core/toolbox/toolbox.ts index b2944a946..afb7de0a0 100644 --- a/core/toolbox/toolbox.ts +++ b/core/toolbox/toolbox.ts @@ -6,6 +6,7 @@ /** * Toolbox from whence to create blocks. + * * @class */ import * as goog from '../../closure/goog/goog.js'; @@ -52,6 +53,7 @@ import {CollapsibleToolboxCategory} from './collapsible_category.js'; /** * Class for a Toolbox. * Creates the toolbox's DOM. + * * @alias Blockly.Toolbox */ export class Toolbox extends DeleteArea implements IAutoHideable, @@ -133,8 +135,9 @@ export class Toolbox extends DeleteArea implements IAutoHideable, /** * Handles the given keyboard shortcut. + * * @param _shortcut The shortcut to be handled. - * @return True if the shortcut has been handled, false otherwise. + * @returns True if the shortcut has been handled, false otherwise. */ onShortcut(_shortcut: KeyboardShortcut): boolean { return false; @@ -170,8 +173,9 @@ export class Toolbox extends DeleteArea implements IAutoHideable, /** * Creates the DOM for the toolbox. + * * @param workspace The workspace this toolbox is on. - * @return The HTML container for the toolbox. + * @returns The HTML container for the toolbox. */ protected createDom_(workspace: WorkspaceSvg): HTMLDivElement { const svg = workspace.getParentSvg(); @@ -191,7 +195,8 @@ export class Toolbox extends DeleteArea implements IAutoHideable, /** * Creates the container div for the toolbox. - * @return The HTML container for the toolbox. + * + * @returns The HTML container for the toolbox. */ protected createContainer_(): HTMLDivElement { const toolboxContainer = (document.createElement('div')); @@ -204,7 +209,8 @@ export class Toolbox extends DeleteArea implements IAutoHideable, /** * Creates the container for all the contents in the toolbox. - * @return The HTML container for the toolbox contents. + * + * @returns The HTML container for the toolbox contents. */ protected createContentsContainer_(): HTMLDivElement { const contentsContainer = (document.createElement('div')); @@ -217,6 +223,7 @@ export class Toolbox extends DeleteArea implements IAutoHideable, /** * Adds event listeners to the toolbox container div. + * * @param container The HTML container for the toolbox. * @param contentsContainer The HTML container for the contents of the * toolbox. @@ -237,6 +244,7 @@ export class Toolbox extends DeleteArea implements IAutoHideable, /** * Handles on click events for when the toolbox or toolbox items are clicked. + * * @param e Click event to handle. */ protected onClick_(e: MouseEvent) { @@ -261,6 +269,7 @@ export class Toolbox extends DeleteArea implements IAutoHideable, /** * Handles key down events for the toolbox. + * * @param e The key down event. */ protected onKeyDown_(e: KeyboardEvent) { @@ -306,7 +315,8 @@ export class Toolbox extends DeleteArea implements IAutoHideable, /** * Creates the flyout based on the toolbox layout. - * @return The flyout for the toolbox. + * + * @returns The flyout for the toolbox. * @throws {Error} If missing a require for `Blockly.HorizontalFlyout`, * `Blockly.VerticalFlyout`, and no flyout plugin is specified. */ @@ -340,6 +350,7 @@ export class Toolbox extends DeleteArea implements IAutoHideable, /** * Fills the toolbox with new toolbox items and removes any old contents. + * * @param toolboxDef Object holding information for creating a toolbox. * @internal */ @@ -360,6 +371,7 @@ export class Toolbox extends DeleteArea implements IAutoHideable, /** * Adds all the toolbox items to the toolbox. + * * @param toolboxDef Array holding objects containing information on the * contents of the toolbox. */ @@ -376,6 +388,7 @@ export class Toolbox extends DeleteArea implements IAutoHideable, /** * Creates and renders the toolbox item. + * * @param toolboxItemDef Any information that can be used to create an item in * the toolbox. * @param fragment The document fragment to add the child toolbox elements to. @@ -411,6 +424,7 @@ export class Toolbox extends DeleteArea implements IAutoHideable, /** * Adds an item to the toolbox. + * * @param toolboxItem The item in the toolbox. */ protected addToolboxItem_(toolboxItem: IToolboxItem) { @@ -428,7 +442,8 @@ export class Toolbox extends DeleteArea implements IAutoHideable, /** * Gets the items in the toolbox. - * @return The list of items in the toolbox. + * + * @returns The list of items in the toolbox. */ getToolboxItems(): IToolboxItem[] { return this.contents_; @@ -436,6 +451,7 @@ export class Toolbox extends DeleteArea implements IAutoHideable, /** * Adds a style on the toolbox. Usually used to change the cursor. + * * @param style The name of the class to add. * @internal */ @@ -445,6 +461,7 @@ export class Toolbox extends DeleteArea implements IAutoHideable, /** * Removes a style from the toolbox. Usually used to change the cursor. + * * @param style The name of the class to remove. * @internal */ @@ -455,7 +472,8 @@ export class Toolbox extends DeleteArea implements IAutoHideable, /** * Returns the bounding rectangle of the drag target area in pixel units * relative to viewport. - * @return The component's bounding box. Null if drag target area should be + * + * @returns The component's bounding box. Null if drag target area should be * ignored. */ override getClientRect(): Rect|null { @@ -491,9 +509,10 @@ export class Toolbox extends DeleteArea implements IAutoHideable, * this area. * This method should check if the element is deletable and is always called * before onDragEnter/onDragOver/onDragExit. + * * @param element The block or bubble currently being dragged. * @param _couldConnect Whether the element could could connect to another. - * @return Whether the element provided would be deleted if dropped on this + * @returns Whether the element provided would be deleted if dropped on this * area. */ override wouldDelete(element: IDraggable, _couldConnect: boolean): boolean { @@ -509,6 +528,7 @@ export class Toolbox extends DeleteArea implements IAutoHideable, /** * Handles when a cursor with a block or bubble enters this drag target. + * * @param _dragElement The block or bubble currently being dragged. */ override onDragEnter(_dragElement: IDraggable) { @@ -517,6 +537,7 @@ export class Toolbox extends DeleteArea implements IAutoHideable, /** * Handles when a cursor with a block or bubble exits this drag target. + * * @param _dragElement The block or bubble currently being dragged. */ override onDragExit(_dragElement: IDraggable) { @@ -526,6 +547,7 @@ export class Toolbox extends DeleteArea implements IAutoHideable, /** * Handles when a block or bubble is dropped on this component. * Should not handle delete here. + * * @param _dragElement The block or bubble currently being dragged. */ override onDrop(_dragElement: IDraggable) { @@ -534,6 +556,7 @@ export class Toolbox extends DeleteArea implements IAutoHideable, /** * Updates the internal wouldDelete_ state. + * * @param wouldDelete The new value for the wouldDelete state. */ protected override updateWouldDelete_(wouldDelete: boolean) { @@ -554,6 +577,7 @@ export class Toolbox extends DeleteArea implements IAutoHideable, * Adds or removes the CSS style of the cursor over the toolbox based whether * the block or bubble over it is expected to be deleted if dropped (using the * internal this.wouldDelete_ property). + * * @param addStyle Whether the style should be added or removed. */ protected updateCursorDeleteStyle_(addStyle: boolean) { @@ -568,8 +592,9 @@ export class Toolbox extends DeleteArea implements IAutoHideable, /** * Gets the toolbox item with the given ID. + * * @param id The ID of the toolbox item. - * @return The toolbox item with the given ID, or null if no item exists. + * @returns The toolbox item with the given ID, or null if no item exists. */ getToolboxItemById(id: string): IToolboxItem|null { return this.contentMap_[id] || null; @@ -577,7 +602,8 @@ export class Toolbox extends DeleteArea implements IAutoHideable, /** * Gets the width of the toolbox. - * @return The width of the toolbox. + * + * @returns The width of the toolbox. */ getWidth(): number { return this.width_; @@ -585,7 +611,8 @@ export class Toolbox extends DeleteArea implements IAutoHideable, /** * Gets the height of the toolbox. - * @return The width of the toolbox. + * + * @returns The width of the toolbox. */ getHeight(): number { return this.height_; @@ -593,7 +620,8 @@ export class Toolbox extends DeleteArea implements IAutoHideable, /** * Gets the toolbox flyout. - * @return The toolbox flyout. + * + * @returns The toolbox flyout. */ getFlyout(): IFlyout|null { return this.flyout_; @@ -601,7 +629,8 @@ export class Toolbox extends DeleteArea implements IAutoHideable, /** * Gets the workspace for the toolbox. - * @return The parent workspace for the toolbox. + * + * @returns The parent workspace for the toolbox. */ getWorkspace(): WorkspaceSvg { return this.workspace_; @@ -609,7 +638,8 @@ export class Toolbox extends DeleteArea implements IAutoHideable, /** * Gets the selected item. - * @return The selected item, or null if no item is currently selected. + * + * @returns The selected item, or null if no item is currently selected. */ getSelectedItem(): ISelectableToolboxItem|null { return this.selectedItem_; @@ -617,7 +647,8 @@ export class Toolbox extends DeleteArea implements IAutoHideable, /** * Gets the previously selected item. - * @return The previously selected item, or null if no item was previously + * + * @returns The previously selected item, or null if no item was previously * selected. */ getPreviouslySelectedItem(): ISelectableToolboxItem|null { @@ -626,7 +657,8 @@ export class Toolbox extends DeleteArea implements IAutoHideable, /** * Gets whether or not the toolbox is horizontal. - * @return True if the toolbox is horizontal, false if the toolbox is + * + * @returns True if the toolbox is horizontal, false if the toolbox is * vertical. */ isHorizontal(): boolean { @@ -671,6 +703,7 @@ export class Toolbox extends DeleteArea implements IAutoHideable, /** * Handles resizing the toolbox when a toolbox item resizes. + * * @internal */ handleToolboxItemResize() { @@ -698,6 +731,7 @@ export class Toolbox extends DeleteArea implements IAutoHideable, /** * Updates the category colours and background colour of selected categories. + * * @internal */ refreshTheme() { @@ -725,6 +759,7 @@ export class Toolbox extends DeleteArea implements IAutoHideable, /** * Shows or hides the toolbox. + * * @param isVisible True if toolbox should be visible. */ setVisible(isVisible: boolean) { @@ -741,6 +776,7 @@ export class Toolbox extends DeleteArea implements IAutoHideable, /** * Hides the component. Called in WorkspaceSvg.hideChaff. + * * @param onlyClosePopups Whether only popups should be closed. * Flyouts should not be closed if this is true. */ @@ -753,6 +789,7 @@ export class Toolbox extends DeleteArea implements IAutoHideable, /** * Sets the given item as selected. * No-op if the item is not selectable. + * * @param newItem The toolbox item to select. */ setSelectedItem(newItem: IToolboxItem|null) { @@ -789,9 +826,10 @@ export class Toolbox extends DeleteArea implements IAutoHideable, /** * Decides whether the old item should be deselected. + * * @param oldItem The previously selected toolbox item. * @param newItem The newly selected toolbox item. - * @return True if the old item should be deselected, false otherwise. + * @returns True if the old item should be deselected, false otherwise. */ protected shouldDeselectItem_( oldItem: ISelectableToolboxItem|null, @@ -804,9 +842,10 @@ export class Toolbox extends DeleteArea implements IAutoHideable, /** * Decides whether the new item should be selected. + * * @param oldItem The previously selected toolbox item. * @param newItem The newly selected toolbox item. - * @return True if the new item should be selected, false otherwise. + * @returns True if the new item should be selected, false otherwise. */ protected shouldSelectItem_( oldItem: ISelectableToolboxItem|null, @@ -817,6 +856,7 @@ export class Toolbox extends DeleteArea implements IAutoHideable, /** * Deselects the given item, marks it as unselected, and updates aria state. + * * @param item The previously selected toolbox item which should be * deselected. */ @@ -830,6 +870,7 @@ export class Toolbox extends DeleteArea implements IAutoHideable, /** * Selects the given item, marks it selected, and updates aria state. + * * @param oldItem The previously selected toolbox item. * @param newItem The newly selected toolbox item. */ @@ -845,6 +886,7 @@ export class Toolbox extends DeleteArea implements IAutoHideable, /** * Selects the toolbox item by its position in the list of toolbox items. + * * @param position The position of the item to select. */ selectItemByPosition(position: number) { @@ -858,6 +900,7 @@ export class Toolbox extends DeleteArea implements IAutoHideable, /** * Decides whether to hide or show the flyout depending on the selected item. + * * @param oldItem The previously selected toolbox item. * @param newItem The newly selected toolbox item. */ @@ -875,6 +918,7 @@ export class Toolbox extends DeleteArea implements IAutoHideable, /** * Emits an event when a new toolbox item is selected. + * * @param oldItem The previously selected toolbox item. * @param newItem The newly selected toolbox item. */ @@ -894,7 +938,8 @@ export class Toolbox extends DeleteArea implements IAutoHideable, /** * Closes the current item if it is expanded, or selects the parent. - * @return True if a parent category was selected, false otherwise. + * + * @returns True if a parent category was selected, false otherwise. */ private selectParent_(): boolean { if (!this.selectedItem_) { @@ -918,7 +963,8 @@ export class Toolbox extends DeleteArea implements IAutoHideable, /** * Selects the first child of the currently selected item, or nothing if the * toolbox item has no children. - * @return True if a child category was selected, false otherwise. + * + * @returns True if a child category was selected, false otherwise. */ private selectChild_(): boolean { if (!this.selectedItem_ || !this.selectedItem_.isCollapsible()) { @@ -936,7 +982,8 @@ export class Toolbox extends DeleteArea implements IAutoHideable, /** * Selects the next visible toolbox item. - * @return True if a next category was selected, false otherwise. + * + * @returns True if a next category was selected, false otherwise. */ private selectNext_(): boolean { if (!this.selectedItem_) { @@ -959,7 +1006,8 @@ export class Toolbox extends DeleteArea implements IAutoHideable, /** * Selects the previous visible toolbox item. - * @return True if a previous category was selected, false otherwise. + * + * @returns True if a previous category was selected, false otherwise. */ private selectPrevious_(): boolean { if (!this.selectedItem_) { diff --git a/core/toolbox/toolbox_item.ts b/core/toolbox/toolbox_item.ts index 0770f5327..d3010b32d 100644 --- a/core/toolbox/toolbox_item.ts +++ b/core/toolbox/toolbox_item.ts @@ -6,6 +6,7 @@ /** * An item in the toolbox. + * * @class */ import * as goog from '../../closure/goog/goog.js'; @@ -21,6 +22,7 @@ import type {WorkspaceSvg} from '../workspace_svg.js'; /** * Class for an item in the toolbox. + * * @alias Blockly.ToolboxItem */ export class ToolboxItem implements IToolboxItem { @@ -70,7 +72,8 @@ export class ToolboxItem implements IToolboxItem { /** * Gets the div for the toolbox item. - * @return The div for the toolbox item. + * + * @returns The div for the toolbox item. */ getDiv(): Element|null { return null; @@ -81,7 +84,8 @@ export class ToolboxItem implements IToolboxItem { * The parent toolbox element receives clicks. The parent toolbox will add an * ID to this element so it can pass the onClick event to the correct * toolboxItem. - * @return The HTML element that receives clicks, or null if this item should + * + * @returns The HTML element that receives clicks, or null if this item should * not receive clicks. */ getClickTarget(): Element|null { @@ -90,7 +94,8 @@ export class ToolboxItem implements IToolboxItem { /** * Gets a unique identifier for this toolbox item. - * @return The ID for the toolbox item. + * + * @returns The ID for the toolbox item. */ getId(): string { return this.id_; @@ -98,7 +103,8 @@ export class ToolboxItem implements IToolboxItem { /** * Gets the parent if the toolbox item is nested. - * @return The parent toolbox item, or null if this toolbox item is not + * + * @returns The parent toolbox item, or null if this toolbox item is not * nested. */ getParent(): ICollapsibleToolboxItem|null { @@ -107,7 +113,8 @@ export class ToolboxItem implements IToolboxItem { /** * Gets the nested level of the category. - * @return The nested level of the category. + * + * @returns The nested level of the category. * @internal */ getLevel(): number { @@ -116,7 +123,8 @@ export class ToolboxItem implements IToolboxItem { /** * Whether the toolbox item is selectable. - * @return True if the toolbox item can be selected. + * + * @returns True if the toolbox item can be selected. */ isSelectable(): boolean { return false; @@ -124,7 +132,8 @@ export class ToolboxItem implements IToolboxItem { /** * Whether the toolbox item is collapsible. - * @return True if the toolbox item is collapsible. + * + * @returns True if the toolbox item is collapsible. */ isCollapsible(): boolean { return false; @@ -136,6 +145,7 @@ export class ToolboxItem implements IToolboxItem { /** * Sets whether the category is visible or not. * For a category to be visible its parent category must also be expanded. + * * @param _isVisible True if category should be visible. */ setVisible_(_isVisible: boolean) {} diff --git a/core/tooltip.ts b/core/tooltip.ts index 915e545d7..9cece2c06 100644 --- a/core/tooltip.ts +++ b/core/tooltip.ts @@ -11,6 +11,7 @@ * If the tooltip is a string, or a function that returns a string, that message * will be displayed. If the tooltip is an SVG element, then that object's * tooltip will be used. Third, call bindMouseEvents(e) passing the SVG element. + * * @namespace Blockly.Tooltip */ import * as goog from '../closure/goog/goog.js'; @@ -26,6 +27,7 @@ import * as blocklyString from './utils/string.js'; * Either a string, an object containing a tooltip property, or a function which * returns either a string, or another arbitrarily nested function which * eventually unwinds to a string. + * * @alias Blockly.Tooltip.TipInfo */ export type TipInfo = @@ -36,6 +38,7 @@ export type TipInfo = * 1st parameter: the div element to render content into. * 2nd parameter: the element being moused over (i.e., the element for which the * tooltip should be shown). + * * @alias Blockly.Tooltip.CustomTooltip */ export type CustomTooltip = (p1: Element, p2: Element) => AnyDuringMigration; @@ -50,6 +53,7 @@ let customTooltip: CustomTooltip|undefined = undefined; /** * Sets a custom function that will be called if present instead of the default * tooltip UI. + * * @param customFn A custom tooltip used to render an alternate tooltip UI. * @alias Blockly.Tooltip.setCustomTooltip */ @@ -59,6 +63,7 @@ export function setCustomTooltip(customFn: CustomTooltip) { /** * Gets the custom tooltip function. + * * @returns The custom tooltip function, if defined. */ export function getCustomTooltip(): CustomTooltip|undefined { @@ -70,6 +75,7 @@ let visible = false; /** * Returns whether or not a tooltip is showing + * * @returns True if a tooltip is showing * @alias Blockly.Tooltip.isVisible */ @@ -82,6 +88,7 @@ let blocked = false; /** * Maximum width (in characters) of a tooltip. + * * @alias Blockly.Tooltip.LIMIT */ export const LIMIT = 50; @@ -113,30 +120,35 @@ let poisonedElement: AnyDuringMigration = null; /** * Horizontal offset between mouse cursor and tooltip. + * * @alias Blockly.Tooltip.OFFSET_X */ export const OFFSET_X = 0; /** * Vertical offset between mouse cursor and tooltip. + * * @alias Blockly.Tooltip.OFFSET_Y */ export const OFFSET_Y = 10; /** * Radius mouse can move before killing tooltip. + * * @alias Blockly.Tooltip.RADIUS_OK */ export const RADIUS_OK = 10; /** * Delay before tooltip appears. + * * @alias Blockly.Tooltip.HOVER_MS */ export const HOVER_MS = 750; /** * Horizontal padding between tooltip and screen edge. + * * @alias Blockly.Tooltip.MARGINS */ export const MARGINS = 5; @@ -146,6 +158,7 @@ let containerDiv: HTMLDivElement|null = null; /** * Returns the HTML tooltip container. + * * @returns The HTML tooltip container. * @alias Blockly.Tooltip.getDiv */ @@ -155,8 +168,9 @@ export function getDiv(): HTMLDivElement|null { /** * Returns the tooltip text for the given element. + * * @param object The object to get the tooltip text of. - * @return The tooltip text of the element. + * @returns The tooltip text of the element. * @alias Blockly.Tooltip.getTooltipOfObject */ export function getTooltipOfObject(object: AnyDuringMigration|null): string { @@ -177,8 +191,9 @@ export function getTooltipOfObject(object: AnyDuringMigration|null): string { /** * Returns the target object that the given object is targeting for its * tooltip. Could be the object itself. + * * @param obj The object are trying to find the target tooltip object of. - * @return The target tooltip object. + * @returns The target tooltip object. */ function getTargetObject(obj: object|null): {tooltip: AnyDuringMigration}|null { while (obj && (obj as any).tooltip) { @@ -193,6 +208,7 @@ function getTargetObject(obj: object|null): {tooltip: AnyDuringMigration}|null { /** * Create the tooltip div and inject it onto the page. + * * @alias Blockly.Tooltip.createDom */ export function createDom() { @@ -208,6 +224,7 @@ export function createDom() { /** * Binds the required mouse events onto an SVG element. + * * @param element SVG element onto which tooltip is to be bound. * @alias Blockly.Tooltip.bindMouseEvents */ @@ -226,6 +243,7 @@ export function bindMouseEvents(element: Element) { /** * Unbinds tooltip mouse events from the SVG element. + * * @param element SVG element onto which tooltip is bound. * @alias Blockly.Tooltip.unbindMouseEvents */ @@ -242,6 +260,7 @@ export function unbindMouseEvents(element: Element) { /** * Hide the tooltip if the mouse is over a different object. * Initialize the tooltip to potentially appear for this object. + * * @param e Mouse event. */ function onMouseOver(e: Event) { @@ -263,6 +282,7 @@ function onMouseOver(e: Event) { /** * Hide the tooltip if the mouse leaves the object and enters the workspace. + * * @param _e Mouse event. */ function onMouseOut(_e: Event) { @@ -285,6 +305,7 @@ function onMouseOut(_e: Event) { /** * When hovering over an element, schedule a tooltip to be shown. If a tooltip * is already visible, hide it if the mouse strays out of a certain radius. + * * @param e Mouse event. */ function onMouseMove(e: Event) { @@ -324,6 +345,7 @@ function onMouseMove(e: Event) { /** * Dispose of the tooltip. + * * @alias Blockly.Tooltip.dispose * @internal */ @@ -335,6 +357,7 @@ export function dispose() { /** * Hide the tooltip. + * * @alias Blockly.Tooltip.hide */ export function hide() { @@ -352,6 +375,7 @@ export function hide() { /** * Hide any in-progress tooltips and block showing new tooltips until the next * call to unblock(). + * * @alias Blockly.Tooltip.block * @internal */ @@ -363,6 +387,7 @@ export function block() { /** * Unblock tooltips: allow them to be scheduled and shown according to their own * logic. + * * @alias Blockly.Tooltip.unblock * @internal */ @@ -399,6 +424,7 @@ function renderDefaultContent() { /** * Gets the coordinates for the tooltip div, taking into account the edges of * the screen to prevent showing the tooltip offscreen. + * * @param rtl True if the tooltip should be in right-to-left layout. * @returns Coordinates at which the tooltip div should be placed. */ diff --git a/core/touch.ts b/core/touch.ts index ea1b8e3f2..1ad4b476f 100644 --- a/core/touch.ts +++ b/core/touch.ts @@ -6,6 +6,7 @@ /** * Touch handling for Blockly. + * * @namespace Blockly.Touch */ import * as goog from '../closure/goog/goog.js'; @@ -48,6 +49,7 @@ let touchIdentifier_: string|null = null; /** * The TOUCH_MAP lookup dictionary specifies additional touch events to fire, * in conjunction with mouse events. + * * @alias Blockly.Touch.TOUCH_MAP */ export const TOUCH_MAP: {[key: string]: string[]} = globalThis['PointerEvent'] ? @@ -77,6 +79,7 @@ let longPid_: AnyDuringMigration = 0; * by Chrome. This function is fired on any touchstart event, queues a task, * which after about a second opens the context menu. The tasks is killed * if the touch event terminates early. + * * @param e Touch start event. * @param gesture The gesture that triggered this longStart. * @alias Blockly.Touch.longStart @@ -111,6 +114,7 @@ export function longStart(e: Event, gesture: Gesture) { /** * Nope, that's not a long-press. Either touchend or touchcancel was fired, * or a drag hath begun. Kill the queued long-press task. + * * @alias Blockly.Touch.longStop * @internal */ @@ -125,6 +129,7 @@ export function longStop() { * Clear the touch identifier that tracks which touch stream to pay attention * to. This ends the current drag/gesture and allows other pointers to be * captured. + * * @alias Blockly.Touch.clearTouchIdentifier */ export function clearTouchIdentifier() { @@ -135,8 +140,9 @@ export function clearTouchIdentifier() { * Decide whether Blockly should handle or ignore this event. * Mouse and touch events require special checks because we only want to deal * with one touch stream at a time. All other events should always be handled. + * * @param e The event to check. - * @return True if this event should be passed through to the registered + * @returns True if this event should be passed through to the registered * handler; false if it should be blocked. * @alias Blockly.Touch.shouldHandleEvent */ @@ -147,8 +153,9 @@ export function shouldHandleEvent(e: Event|PseudoEvent): boolean { /** * Get the touch identifier from the given event. If it was a mouse event, the * identifier is the string 'mouse'. + * * @param e Mouse event or touch event. - * @return The touch identifier from the first changed touch, if defined. + * @returns The touch identifier from the first changed touch, if defined. * Otherwise 'mouse'. * @alias Blockly.Touch.getTouchIdentifierFromEvent */ @@ -193,8 +200,9 @@ export function getTouchIdentifierFromEvent(e: Event|PseudoEvent): string { * If the current identifier was unset, save the identifier from the * event. This starts a drag/gesture, during which touch events with other * identifiers will be silently ignored. + * * @param e Mouse event or touch event. - * @return Whether the identifier on the event matches the current saved + * @returns Whether the identifier on the event matches the current saved * identifier. * @alias Blockly.Touch.checkTouchIdentifier */ @@ -224,6 +232,7 @@ export function checkTouchIdentifier(e: Event|PseudoEvent): boolean { /** * Set an event's clientX and clientY from its first changed touch. Use this to * make a touch event work in a mouse event handler. + * * @param e A touch event. * @alias Blockly.Touch.setClientFromTouch */ @@ -246,8 +255,9 @@ export function setClientFromTouch(e: Event|PseudoEvent) { /** * Check whether a given event is a mouse, touch, or pointer event. + * * @param e An event. - * @return True if it is a mouse, touch, or pointer event; false otherwise. + * @returns True if it is a mouse, touch, or pointer event; false otherwise. * @alias Blockly.Touch.isMouseOrTouchEvent */ export function isMouseOrTouchEvent(e: Event|PseudoEvent): boolean { @@ -257,8 +267,9 @@ export function isMouseOrTouchEvent(e: Event|PseudoEvent): boolean { /** * Check whether a given event is a touch event or a pointer event. + * * @param e An event. - * @return True if it is a touch or pointer event; false otherwise. + * @returns True if it is a touch or pointer event; false otherwise. * @alias Blockly.Touch.isTouchEvent */ export function isTouchEvent(e: Event|PseudoEvent): boolean { @@ -268,8 +279,9 @@ export function isTouchEvent(e: Event|PseudoEvent): boolean { /** * Split an event into an array of events, one per changed touch or mouse * point. + * * @param e A mouse event or a touch event with one or more changed touches. - * @return An array of events or pseudo events. + * @returns An array of events or pseudo events. * Each pseudo-touch event will have exactly one changed touch and there * will be no real touch events. * @alias Blockly.Touch.splitEventByTouches diff --git a/core/touch_gesture.ts b/core/touch_gesture.ts index 3fe02db04..4b2f94d05 100644 --- a/core/touch_gesture.ts +++ b/core/touch_gesture.ts @@ -7,6 +7,7 @@ /** * The class extends Gesture to support pinch to zoom * for both pointer and touch events. + * * @class */ import * as goog from '../closure/goog/goog.js'; @@ -30,6 +31,7 @@ const ZOOM_OUT_MULTIPLIER = 6; /** * Class for one gesture. + * * @alias Blockly.TouchGesture */ export class TouchGesture extends Gesture { @@ -65,6 +67,7 @@ export class TouchGesture extends Gesture { /** * Start a gesture: update the workspace to indicate that a gesture is in * progress and bind mousemove and mouseup handlers. + * * @param e A mouse down, touch start or pointer down event. * @internal */ @@ -84,6 +87,7 @@ export class TouchGesture extends Gesture { * opt_noCaptureIdentifier. * In addition, binding a second mouse down event to detect multi-touch * events. + * * @param e A mouse down or touch start event. * @internal */ @@ -104,6 +108,7 @@ export class TouchGesture extends Gesture { /** * Handle a mouse down, touch start, or pointer down event. + * * @param e A mouse down, touch start, or pointer down event. * @internal */ @@ -123,6 +128,7 @@ export class TouchGesture extends Gesture { /** * Handle a mouse move, touch move, or pointer move event. + * * @param e A mouse move, touch move, or pointer move event. * @internal */ @@ -146,6 +152,7 @@ export class TouchGesture extends Gesture { /** * Handle a mouse up, touch end, or pointer up event. + * * @param e A mouse up, touch end, or pointer up event. * @internal */ @@ -168,7 +175,8 @@ export class TouchGesture extends Gesture { /** * Whether this gesture is part of a multi-touch gesture. - * @return Whether this gesture is part of a multi-touch gesture. + * + * @returns Whether this gesture is part of a multi-touch gesture. * @internal */ isMultiTouch(): boolean { @@ -177,6 +185,7 @@ export class TouchGesture extends Gesture { /** * Sever all links from this object. + * * @internal */ override dispose() { @@ -190,6 +199,7 @@ export class TouchGesture extends Gesture { /** * Handle a touch start or pointer down event and keep track of current * pointers. + * * @param e A touch start, or pointer down event. * @internal */ @@ -211,6 +221,7 @@ export class TouchGesture extends Gesture { /** * Handle a touch move or pointer move event and zoom in/out if two pointers * are on the screen. + * * @param e A touch move, or pointer move event. * @internal */ @@ -228,6 +239,7 @@ export class TouchGesture extends Gesture { /** * Handle pinch zoom gesture. + * * @param e A touch move, or pointer move event. */ private handlePinch_(e: MouseEvent) { @@ -253,6 +265,7 @@ export class TouchGesture extends Gesture { /** * Handle a touch end or pointer end event and end the gesture. + * * @param e A touch end, or pointer end event. * @internal */ @@ -269,8 +282,9 @@ export class TouchGesture extends Gesture { /** * Helper function returning the current touch point coordinate. + * * @param e A touch or pointer event. - * @return The current touch point coordinate + * @returns The current touch point coordinate * @internal */ getTouchPoint(e: Event): Coordinate|null { diff --git a/core/trashcan.ts b/core/trashcan.ts index 9e2741d70..25b7724a4 100644 --- a/core/trashcan.ts +++ b/core/trashcan.ts @@ -6,6 +6,7 @@ /** * Object representing a trash can icon. + * * @class */ import * as goog from '../closure/goog/goog.js'; @@ -45,6 +46,7 @@ import type {WorkspaceSvg} from './workspace_svg.js'; /** * Class for a trash can. + * * @alias Blockly.Trashcan */ export class Trashcan extends DeleteArea implements IAutoHideable, @@ -62,6 +64,7 @@ export class Trashcan extends DeleteArea implements IAutoHideable, /** * The trashcan flyout. + * * @internal */ flyout: IFlyout|null = null; @@ -140,7 +143,8 @@ export class Trashcan extends DeleteArea implements IAutoHideable, /** * Create the trash can elements. - * @return The trash can's SVG group. + * + * @returns The trash can's SVG group. */ createDom(): SVGElement { /* Here's the markup that will be generated: @@ -233,6 +237,7 @@ export class Trashcan extends DeleteArea implements IAutoHideable, /** * Dispose of this trash can. * Unlink from all DOM elements to prevent memory leaks. + * * @suppress {checkTypes} */ dispose() { @@ -249,7 +254,8 @@ export class Trashcan extends DeleteArea implements IAutoHideable, /** * Whether the trashcan has contents. - * @return True if the trashcan has contents. + * + * @returns True if the trashcan has contents. */ private hasContents_(): boolean { return !!this.contents_.length; @@ -257,7 +263,8 @@ export class Trashcan extends DeleteArea implements IAutoHideable, /** * Returns true if the trashcan contents-flyout is currently open. - * @return True if the trashcan contents-flyout is currently open. + * + * @returns True if the trashcan contents-flyout is currently open. */ contentsIsOpen(): boolean { return !!this.flyout && this.flyout.isVisible(); @@ -287,6 +294,7 @@ export class Trashcan extends DeleteArea implements IAutoHideable, /** * Hides the component. Called in WorkspaceSvg.hideChaff. + * * @param onlyClosePopups Whether only popups should be closed. * Flyouts should not be closed if this is true. */ @@ -315,6 +323,7 @@ export class Trashcan extends DeleteArea implements IAutoHideable, * Positions the trashcan. * It is positioned in the opposite corner to the corner the * categories/toolbox starts at. + * * @param metrics The workspace metrics. * @param savedPositions List of rectangles that are already on the workspace. */ @@ -348,7 +357,8 @@ export class Trashcan extends DeleteArea implements IAutoHideable, /** * Returns the bounding rectangle of the UI element in pixel units relative to * the Blockly injection div. - * @return The UI elements's bounding box. Null if bounding box should be + * + * @returns The UI elements's bounding box. Null if bounding box should be * ignored by other UI elements. */ getBoundingRectangle(): Rect|null { @@ -360,7 +370,8 @@ export class Trashcan extends DeleteArea implements IAutoHideable, /** * Returns the bounding rectangle of the drag target area in pixel units * relative to viewport. - * @return The component's bounding box. Null if drag target area should be + * + * @returns The component's bounding box. Null if drag target area should be * ignored. */ override getClientRect(): Rect|null { @@ -379,6 +390,7 @@ export class Trashcan extends DeleteArea implements IAutoHideable, /** * Handles when a cursor with a block or bubble is dragged over this drag * target. + * * @param _dragElement The block or bubble currently being dragged. */ override onDragOver(_dragElement: IDraggable) { @@ -387,6 +399,7 @@ export class Trashcan extends DeleteArea implements IAutoHideable, /** * Handles when a cursor with a block or bubble exits this drag target. + * * @param _dragElement The block or bubble currently being dragged. */ override onDragExit(_dragElement: IDraggable) { @@ -396,6 +409,7 @@ export class Trashcan extends DeleteArea implements IAutoHideable, /** * Handles when a block or bubble is dropped on this component. * Should not handle delete here. + * * @param _dragElement The block or bubble currently being dragged. */ override onDrop(_dragElement: IDraggable) { @@ -404,6 +418,7 @@ export class Trashcan extends DeleteArea implements IAutoHideable, /** * Flip the lid open or shut. + * * @param state True if open. * @internal */ @@ -442,6 +457,7 @@ export class Trashcan extends DeleteArea implements IAutoHideable, /** * Set the angle of the trashcan's lid. + * * @param lidAngle The angle at which to set the lid. */ private setLidAngle_(lidAngle: number) { @@ -457,6 +473,7 @@ export class Trashcan extends DeleteArea implements IAutoHideable, /** * Sets the minimum openness of the trashcan lid. If the lid is currently * closed, this will update lid's position. + * * @param newMin The new minimum openness of the lid. Should be between 0 * and 1. */ @@ -485,6 +502,7 @@ export class Trashcan extends DeleteArea implements IAutoHideable, /** * Fires a UI event for trashcan flyout open or close. + * * @param trashcanOpen Whether the flyout is opening. */ private fireUiEvent_(trashcanOpen: boolean) { @@ -495,6 +513,7 @@ export class Trashcan extends DeleteArea implements IAutoHideable, /** * Prevents a workspace scroll and click event if the trashcan has blocks. + * * @param e A mouse down event. */ private blockMouseDownWhenOpenable_(e: Event) { @@ -526,6 +545,7 @@ export class Trashcan extends DeleteArea implements IAutoHideable, /** * Handle a BLOCK_DELETE event. Adds deleted blocks oldXml to the content * array. + * * @param event Workspace event. */ private onDelete_(event: Abstract) { @@ -553,8 +573,9 @@ export class Trashcan extends DeleteArea implements IAutoHideable, /** * Converts JSON representing a block into text that can be stored in the * content array. + * * @param json A JSON representation of a block's state. - * @return A BlockInfo object corresponding to the JSON, cleaned of all + * @returns A BlockInfo object corresponding to the JSON, cleaned of all * unnecessary attributes. */ private cleanBlockJson_(json: blocks.State): BlockInfo { @@ -563,6 +584,7 @@ export class Trashcan extends DeleteArea implements IAutoHideable, /** * Reshape JSON into a nicer format. + * * @param json The JSON to clean. */ function cleanRec(json: blocks.State) { diff --git a/core/utils.ts b/core/utils.ts index 5e31ffaa6..25558d400 100644 --- a/core/utils.ts +++ b/core/utils.ts @@ -6,6 +6,7 @@ /** * Utility methods. + * * @namespace Blockly.utils */ import * as goog from '../closure/goog/goog.js'; @@ -69,6 +70,7 @@ export { /** * Halts the propagation of the event without doing anything else. + * * @param e An event. * @deprecated * @alias Blockly.utils.noEvent @@ -84,8 +86,9 @@ export function noEvent(e: Event) { /** * Returns true if this event is targeting a text input widget? + * * @param e An event. - * @return True if text input. + * @returns True if text input. * @deprecated Use Blockly.browserEvents.isTargetInput instead. * @alias Blockly.utils.isTargetInput */ @@ -101,8 +104,9 @@ export function isTargetInput(e: Event): boolean { /** * Return the coordinates of the top-left corner of this element relative to * its parent. Only for SVG elements and children (e.g. rect, g, path). + * * @param element SVG element to find the coordinates of. - * @return Object with .x and .y properties. + * @returns Object with .x and .y properties. * @deprecated * @alias Blockly.utils.getRelativeXY */ @@ -120,9 +124,10 @@ export function getRelativeXY(element: Element): Coordinate { /** * Return the coordinates of the top-left corner of this element relative to * the div Blockly was injected into. + * * @param element SVG element to find the coordinates of. If this is not a child * of the div Blockly was injected into, the behaviour is undefined. - * @return Object with .x and .y properties. + * @returns Object with .x and .y properties. * @deprecated * @alias Blockly.utils.getInjectionDivXY_ */ @@ -140,8 +145,9 @@ export const getInjectionDivXY_ = getInjectionDivXY; /** * Returns true this event is a right-click. + * * @param e Mouse event. - * @return True if right-click. + * @returns True if right-click. * @deprecated Use Blockly.browserEvents.isRightButton instead. * @alias Blockly.utils.isRightButton */ @@ -157,10 +163,11 @@ export function isRightButton(e: Event): boolean { /** * Returns the converted coordinates of the given mouse event. * The origin (0,0) is the top-left corner of the Blockly SVG. + * * @param e Mouse event. * @param svg SVG element. * @param matrix Inverted screen CTM to use. - * @return Object with .x and .y properties. + * @returns Object with .x and .y properties. * @deprecated Use Blockly.browserEvents.mouseToSvg instead; * @alias Blockly.utils.mouseToSvg */ @@ -176,8 +183,9 @@ export function mouseToSvg( /** * Returns the scroll delta of a mouse event in pixel units. + * * @param e Mouse event. - * @return Scroll delta object with .x and .y properties. + * @returns Scroll delta object with .x and .y properties. * @deprecated Use Blockly.browserEvents.getScrollDeltaPixels instead. * @alias Blockly.utils.getScrollDeltaPixels */ @@ -196,9 +204,10 @@ export function getScrollDeltaPixels(e: WheelEvent): {x: number, y: number} { * %{BKY_MY_MSG} will both be replaced with the value in * Msg['MY_MSG']). Percentage sign characters '%' may be self-escaped * (e.g., '%%'). + * * @param message Text which might contain string table references and * interpolation tokens. - * @return Array of strings and numbers. + * @returns Array of strings and numbers. * @deprecated * @alias Blockly.utils.tokenizeInterpolation */ @@ -217,9 +226,10 @@ export function tokenizeInterpolation(message: string): Array { * Replaces string table references in a message, if the message is a string. * For example, "%{bky_my_msg}" and "%{BKY_MY_MSG}" will both be replaced with * the value in Msg['MY_MSG']. + * * @param message Message, which may be a string that contains string table * references. - * @return String with message references replaced. + * @returns String with message references replaced. * @deprecated * @alias Blockly.utils.replaceMessageReferences */ @@ -238,8 +248,9 @@ export function replaceMessageReferences(message: string| /** * Validates that any %{MSG_KEY} references in the message refer to keys of * the Msg string table. + * * @param message Text which might contain string table references. - * @return True if all message references have matching values. + * @returns True if all message references have matching values. * Otherwise, false. * @deprecated * @alias Blockly.utils.checkMessageReferences @@ -257,7 +268,8 @@ export function checkMessageReferences(message: string): boolean { /** * Generate a unique ID. - * @return A globally unique ID string. + * + * @returns A globally unique ID string. * @deprecated Use Blockly.utils.idGenerator.genUid instead. * @alias Blockly.utils.genUid */ @@ -275,7 +287,8 @@ export function genUid(): string { /** * Check if 3D transforms are supported by adding an element * and attempting to set the property. - * @return True if 3D transforms are supported. + * + * @returns True if 3D transforms are supported. * @deprecated * @alias Blockly.utils.is3dSupported */ @@ -293,7 +306,8 @@ export function is3dSupported(): boolean { /** * Get the position of the current viewport in window coordinates. This takes * scroll into account. - * @return An object containing window width, height, and scroll position in + * + * @returns An object containing window width, height, and scroll position in * window coordinates. * @alias Blockly.utils.getViewportBBox * @deprecated @@ -312,9 +326,10 @@ export function getViewportBBox(): Rect { /** * Removes the first occurrence of a particular value from an array. + * * @param arr Array from which to remove value. * @param value Value to remove. - * @return True if an element was removed. + * @returns True if an element was removed. * @alias Blockly.utils.arrayRemove * @deprecated * @internal @@ -330,7 +345,8 @@ export function arrayRemove( /** * Gets the document scroll distance as a coordinate object. * Copied from Closure's goog.dom.getDocumentScroll. - * @return Object with values 'x' and 'y'. + * + * @returns Object with values 'x' and 'y'. * @deprecated * @alias Blockly.utils.getDocumentScroll */ @@ -348,10 +364,11 @@ export function getDocumentScroll(): Coordinate { /** * Get a map of all the block's descendants mapping their type to the number of * children with that type. + * * @param block The block to map. * @param opt_stripFollowing Optionally ignore all following statements (blocks * that are not inside a value or statement input of the block). - * @return Map of types to type counts for descendants of the bock. + * @returns Map of types to type counts for descendants of the bock. * @deprecated * @alias Blockly.utils.getBlockTypeCounts */ @@ -367,11 +384,12 @@ export function getBlockTypeCounts( /** * Converts screen coordinates to workspace coordinates. + * * @param ws The workspace to find the coordinates on. * @param screenCoordinates The screen coordinates to be converted to workspace * coordinates * @deprecated - * @return The workspace coordinates. + * @returns The workspace coordinates. */ export function screenToWsCoordinates( ws: WorkspaceSvg, screenCoordinates: Coordinate): Coordinate { @@ -389,9 +407,10 @@ export function screenToWsCoordinates( /** * Parse a block colour from a number or string, as provided in a block * definition. + * * @param colour HSV hue value (0 to 360), #RRGGBB string, or a message * reference string pointing to one of those two values. - * @return An object containing the colour as a #RRGGBB string, and the hue if + * @returns An object containing the colour as a #RRGGBB string, and the hue if * the input was an HSV hue value. * @throws {Error} If the colour cannot be parsed. * @deprecated @@ -411,6 +430,7 @@ export function parseBlockColour(colour: number| /** * Calls a function after the page has loaded, possibly immediately. + * * @param fn Function to run. * @throws Error Will throw if no global document can be found (e.g., Node.js). * @deprecated diff --git a/core/utils/aria.ts b/core/utils/aria.ts index 65f787cfc..b0bed04a5 100644 --- a/core/utils/aria.ts +++ b/core/utils/aria.ts @@ -8,6 +8,7 @@ * ARIA-related constants and utilities. * These methods are not specific to Blockly, and could be factored out into * a JavaScript framework such as Closure. + * * @namespace Blockly.utils.aria */ import * as goog from '../../closure/goog/goog.js'; @@ -23,6 +24,7 @@ const ROLE_ATTRIBUTE = 'role'; /** * ARIA role values. * Copied from Closure's goog.a11y.aria.Role + * * @alias Blockly.utils.aria.Role */ export enum Role { @@ -62,6 +64,7 @@ export enum Role { /** * ARIA states and properties. * Copied from Closure's goog.a11y.aria.State + * * @alias Blockly.utils.aria.State */ export enum State { @@ -135,6 +138,7 @@ export function setRole(element: Element, roleName: Role) { /** * Sets the state or property of an element. * Copied from Closure's goog.a11y.aria + * * @param element DOM node where we set state. * @param stateName State attribute being set. * Automatically adds prefix 'aria-' to the state name if the attribute is diff --git a/core/utils/array.ts b/core/utils/array.ts index 7e192c5b0..59002188c 100644 --- a/core/utils/array.ts +++ b/core/utils/array.ts @@ -11,9 +11,10 @@ goog.declareModuleId('Blockly.utils.array'); /** * Removes the first occurrence of a particular value from an array. + * * @param arr Array from which to remove value. * @param value Value to remove. - * @return True if an element was removed. + * @returns True if an element was removed. * @alias Blockly.array.removeElem * @internal */ diff --git a/core/utils/colour.ts b/core/utils/colour.ts index 6d5f1b9df..41dbb0dd0 100644 --- a/core/utils/colour.ts +++ b/core/utils/colour.ts @@ -6,6 +6,7 @@ /** * Utility methods for colour manipulation. + * * @namespace Blockly.utils.colour */ import * as goog from '../../closure/goog/goog.js'; @@ -15,14 +16,16 @@ goog.declareModuleId('Blockly.utils.colour'); /** * The richness of block colours, regardless of the hue. * Must be in the range of 0 (inclusive) to 1 (exclusive). + * * @alias Blockly.utils.colour.hsvSaturation */ let hsvSaturation = 0.45; /** * Get the richness of block colours, regardless of the hue. + * * @alias Blockly.utils.colour.getHsvSaturation - * @return The current richness. + * @returns The current richness. * @internal */ export function getHsvSaturation(): number { @@ -31,6 +34,7 @@ export function getHsvSaturation(): number { /** * Set the richness of block colours, regardless of the hue. + * * @param newSaturation The new richness, in the range of 0 (inclusive) to 1 * (exclusive) * @alias Blockly.utils.colour.setHsvSaturation @@ -43,14 +47,16 @@ export function setHsvSaturation(newSaturation: number) { /** * The intensity of block colours, regardless of the hue. * Must be in the range of 0 (inclusive) to 1 (exclusive). + * * @alias Blockly.utils.colour.hsvValue */ let hsvValue = 0.65; /** * Get the intensity of block colours, regardless of the hue. + * * @alias Blockly.utils.colour.getHsvValue - * @return The current intensity. + * @returns The current intensity. * @internal */ export function getHsvValue(): number { @@ -59,6 +65,7 @@ export function getHsvValue(): number { /** * Set the intensity of block colours, regardless of the hue. + * * @param newValue The new intensity, in the range of 0 (inclusive) to 1 * (exclusive) * @alias Blockly.utils.colour.setHsvValue @@ -75,8 +82,9 @@ export function setHsvValue(newValue: number) { * .parse('#ff0000') -> '#ff0000' * .parse('0xff0000') -> '#ff0000' * .parse('rgb(255, 0, 0)') -> '#ff0000' + * * @param str Colour in some CSS format. - * @return A string containing a hex representation of the colour, or null if + * @returns A string containing a hex representation of the colour, or null if * can't be parsed. * @alias Blockly.utils.colour.parse */ @@ -112,10 +120,11 @@ export function parse(str: string|number): string|null { /** * Converts a colour from RGB to hex representation. + * * @param r Amount of red, int between 0 and 255. * @param g Amount of green, int between 0 and 255. * @param b Amount of blue, int between 0 and 255. - * @return Hex representation of the colour. + * @returns Hex representation of the colour. * @alias Blockly.utils.colour.rgbToHex */ export function rgbToHex(r: number, g: number, b: number): string { @@ -128,9 +137,10 @@ export function rgbToHex(r: number, g: number, b: number): string { /** * Converts a colour to RGB. + * * @param colour String representing colour in any colour format ('#ff0000', * 'red', '0xff000', etc). - * @return RGB representation of the colour. + * @returns RGB representation of the colour. * @alias Blockly.utils.colour.hexToRgb */ export function hexToRgb(colour: string): number[] { @@ -149,10 +159,11 @@ export function hexToRgb(colour: string): number[] { /** * Converts an HSV triplet to hex representation. + * * @param h Hue value in [0, 360]. * @param s Saturation value in [0, 1]. * @param v Brightness in [0, 255]. - * @return Hex representation of the colour. + * @returns Hex representation of the colour. * @alias Blockly.utils.colour.hsvToHex */ export function hsvToHex(h: number, s: number, v: number): string { @@ -209,11 +220,12 @@ export function hsvToHex(h: number, s: number, v: number): string { /** * Blend two colours together, using the specified factor to indicate the * weight given to the first colour. + * * @param colour1 First colour. * @param colour2 Second colour. * @param factor The weight to be given to colour1 over colour2. * Values should be in the range [0, 1]. - * @return Combined colour represented in hex. + * @returns Combined colour represented in hex. * @alias Blockly.utils.colour.blend */ export function blend(colour1: string, colour2: string, factor: number): string| @@ -263,8 +275,9 @@ export const names: {[key: string]: string} = { /** * Convert a hue (HSV model) into an RGB hex triplet. + * * @param hue Hue on a colour wheel (0-360). - * @return RGB code, e.g. '#5ba65b'. + * @returns RGB code, e.g. '#5ba65b'. * @alias Blockly.utils.colour.hueToHex */ export function hueToHex(hue: number): string { diff --git a/core/utils/coordinate.ts b/core/utils/coordinate.ts index 9068a9624..5d2411a14 100644 --- a/core/utils/coordinate.ts +++ b/core/utils/coordinate.ts @@ -8,6 +8,7 @@ * Utility methods for coordinate manipulation. * These methods are not specific to Blockly, and could be factored out into * a JavaScript framework such as Closure. + * * @class */ import * as goog from '../../closure/goog/goog.js'; @@ -16,6 +17,7 @@ goog.declareModuleId('Blockly.utils.Coordinate'); /** * Class for representing coordinates and positions. + * * @alias Blockly.utils.Coordinate */ export class Coordinate { @@ -27,7 +29,8 @@ export class Coordinate { /** * Creates a new copy of this coordinate. - * @return A copy of this coordinate. + * + * @returns A copy of this coordinate. */ clone(): Coordinate { return new Coordinate(this.x, this.y); @@ -35,8 +38,9 @@ export class Coordinate { /** * Scales this coordinate by the given scale factor. + * * @param s The scale factor to use for both x and y dimensions. - * @return This coordinate after scaling. + * @returns This coordinate after scaling. */ scale(s: number): Coordinate { this.x *= s; @@ -47,9 +51,10 @@ export class Coordinate { /** * Translates this coordinate by the given offsets. * respectively. + * * @param tx The value to translate x by. * @param ty The value to translate y by. - * @return This coordinate after translating. + * @returns This coordinate after translating. */ translate(tx: number, ty: number): Coordinate { this.x += tx; @@ -59,9 +64,10 @@ export class Coordinate { /** * Compares coordinates for equality. + * * @param a A Coordinate. * @param b A Coordinate. - * @return True iff the coordinates are equal, or if both are null. + * @returns True iff the coordinates are equal, or if both are null. */ static equals(a: Coordinate|null, b: Coordinate|null): boolean { if (a === b) { @@ -75,9 +81,10 @@ export class Coordinate { /** * Returns the distance between two coordinates. + * * @param a A Coordinate. * @param b A Coordinate. - * @return The distance between `a` and `b`. + * @returns The distance between `a` and `b`. */ static distance(a: Coordinate, b: Coordinate): number { const dx = a.x - b.x; @@ -87,8 +94,9 @@ export class Coordinate { /** * Returns the magnitude of a coordinate. + * * @param a A Coordinate. - * @return The distance between the origin and `a`. + * @returns The distance between the origin and `a`. */ static magnitude(a: Coordinate): number { return Math.sqrt(a.x * a.x + a.y * a.y); @@ -97,9 +105,10 @@ export class Coordinate { /** * Returns the difference between two coordinates as a new * Coordinate. + * * @param a An x/y coordinate. * @param b An x/y coordinate. - * @return A Coordinate representing the difference between `a` and `b`. + * @returns A Coordinate representing the difference between `a` and `b`. */ static difference(a: Coordinate|SVGPoint, b: Coordinate|SVGPoint): Coordinate { @@ -108,9 +117,10 @@ export class Coordinate { /** * Returns the sum of two coordinates as a new Coordinate. + * * @param a An x/y coordinate. * @param b An x/y coordinate. - * @return A Coordinate representing the sum of the two coordinates. + * @returns A Coordinate representing the sum of the two coordinates. */ static sum(a: Coordinate|SVGPoint, b: Coordinate|SVGPoint): Coordinate { return new Coordinate(a.x + b.x, a.y + b.y); diff --git a/core/utils/deprecation.ts b/core/utils/deprecation.ts index a45d2cc93..5c4b959f6 100644 --- a/core/utils/deprecation.ts +++ b/core/utils/deprecation.ts @@ -7,6 +7,7 @@ /** * Helper function for warning developers about deprecations. * This method is not specific to Blockly. + * * @namespace Blockly.utils.deprecation */ import * as goog from '../../closure/goog/goog.js'; @@ -15,6 +16,7 @@ goog.declareModuleId('Blockly.utils.deprecation'); /** * Warn developers that a function or property is deprecated. + * * @param name The name of the function or property. * @param deprecationDate The date of deprecation. * Prefer 'month yyyy' or 'quarter yyyy' format. diff --git a/core/utils/dom.ts b/core/utils/dom.ts index c44fe050e..d7d45bdb2 100644 --- a/core/utils/dom.ts +++ b/core/utils/dom.ts @@ -8,6 +8,7 @@ * Utility methods for DOM manipulation. * These methods are not specific to Blockly, and could be factored out into * a JavaScript framework such as Closure. + * * @namespace Blockly.utils.dom */ import * as goog from '../../closure/goog/goog.js'; @@ -19,18 +20,21 @@ import * as userAgent from './useragent.js'; /** * Required name space for SVG elements. + * * @alias Blockly.utils.dom.SVG_NS */ export const SVG_NS = 'http://www.w3.org/2000/svg'; /** * Required name space for HTML elements. + * * @alias Blockly.utils.dom.HTML_NS */ export const HTML_NS = 'http://www.w3.org/1999/xhtml'; /** * Required name space for XLINK elements. + * * @alias Blockly.utils.dom.XLINK_NS */ export const XLINK_NS = 'http://www.w3.org/1999/xlink'; @@ -38,6 +42,7 @@ export const XLINK_NS = 'http://www.w3.org/1999/xlink'; /** * Node type constants. * https://developer.mozilla.org/en-US/docs/Web/API/Node/nodeType + * * @alias Blockly.utils.dom.NodeType */ export enum NodeType { @@ -60,10 +65,11 @@ let canvasContext: CanvasRenderingContext2D = null as AnyDuringMigration; /** * Helper method for creating SVG elements. + * * @param name Element's tag name. * @param attrs Dictionary of attribute names and values. * @param opt_parent Optional parent on which to append the element. - * @return if name is a string or a more specific type if it a member of Svg. + * @returns if name is a string or a more specific type if it a member of Svg. * @alias Blockly.utils.dom.createSvgElement */ export function createSvgElement( @@ -88,9 +94,10 @@ export function createSvgElement( /** * Add a CSS class to a element. * Similar to Closure's goog.dom.classes.add, except it handles SVG elements. + * * @param element DOM element to add class to. * @param className Name of class to add. - * @return True if class was added, false if already present. + * @returns True if class was added, false if already present. * @alias Blockly.utils.dom.addClass */ export function addClass(element: Element, className: string): boolean { @@ -107,6 +114,7 @@ export function addClass(element: Element, className: string): boolean { /** * Removes multiple calsses from an element. + * * @param element DOM element to remove classes from. * @param classNames A string of one or multiple class names for an element. * @alias Blockly.utils.dom.removeClasses @@ -121,9 +129,10 @@ export function removeClasses(element: Element, classNames: string) { /** * Remove a CSS class from a element. * Similar to Closure's goog.dom.classes.remove, except it handles SVG elements. + * * @param element DOM element to remove class from. * @param className Name of class to remove. - * @return True if class was removed, false if never present. + * @returns True if class was removed, false if never present. * @alias Blockly.utils.dom.removeClass */ export function removeClass(element: Element, className: string): boolean { @@ -149,9 +158,10 @@ export function removeClass(element: Element, className: string): boolean { /** * Checks if an element has the specified CSS class. * Similar to Closure's goog.dom.classes.has, except it handles SVG elements. + * * @param element DOM element to check. * @param className Name of class to check. - * @return True if class exists, false otherwise. + * @returns True if class exists, false otherwise. * @alias Blockly.utils.dom.hasClass */ export function hasClass(element: Element, className: string): boolean { @@ -161,8 +171,9 @@ export function hasClass(element: Element, className: string): boolean { /** * Removes a node from its parent. No-op if not attached to a parent. + * * @param node The node to remove. - * @return The node removed if removed; else, null. + * @returns The node removed if removed; else, null. * @alias Blockly.utils.dom.removeNode */ // Copied from Closure goog.dom.removeNode @@ -173,6 +184,7 @@ export function removeNode(node: Node|null): Node|null { /** * Insert a node after a reference node. * Contrast with node.insertBefore function. + * * @param newNode New element to insert. * @param refNode Existing element to precede new node. * @alias Blockly.utils.dom.insertAfter @@ -192,9 +204,10 @@ export function insertAfter(newNode: Element, refNode: Element) { /** * Whether a node contains another node. + * * @param parent The node that should contain the other node. * @param descendant The node to test presence of. - * @return Whether the parent node contains the descendant node. + * @returns Whether the parent node contains the descendant node. * @alias Blockly.utils.dom.containsNode */ export function containsNode(parent: Node, descendant: Node): boolean { @@ -207,6 +220,7 @@ export function containsNode(parent: Node, descendant: Node): boolean { * Sets the CSS transform property on an element. This function sets the * non-vendor-prefixed and vendor-prefixed versions for backwards compatibility * with older browsers. See https://caniuse.com/#feat=transforms2d + * * @param element Element to which the CSS transform will be applied. * @param transform The value of the CSS `transform` property. * @alias Blockly.utils.dom.setCssTransform @@ -223,6 +237,7 @@ export function setCssTransform(element: Element, transform: string) { /** * Start caching text widths. Every call to this function MUST also call * stopTextWidthCache. Caches must not survive between execution threads. + * * @alias Blockly.utils.dom.startTextWidthCache */ export function startTextWidthCache() { @@ -235,6 +250,7 @@ export function startTextWidthCache() { /** * Stop caching field widths. Unless caching was already on when the * corresponding call to startTextWidthCache was made. + * * @alias Blockly.utils.dom.stopTextWidthCache */ export function stopTextWidthCache() { @@ -246,8 +262,9 @@ export function stopTextWidthCache() { /** * Gets the width of a text element, caching it in the process. + * * @param textElement An SVG 'text' element. - * @return Width of element. + * @returns Width of element. * @alias Blockly.utils.dom.getTextWidth */ export function getTextWidth(textElement: SVGTextElement): number { @@ -287,11 +304,12 @@ export function getTextWidth(textElement: SVGTextElement): number { * Gets the width of a text element using a faster method than `getTextWidth`. * This method requires that we know the text element's font family and size in * advance. Similar to `getTextWidth`, we cache the width we compute. + * * @param textElement An SVG 'text' element. * @param fontSize The font size to use. * @param fontWeight The font weight to use. * @param fontFamily The font family to use. - * @return Width of element. + * @returns Width of element. * @alias Blockly.utils.dom.getFastTextWidth */ export function getFastTextWidth( @@ -307,11 +325,12 @@ export function getFastTextWidth( * advance. Similar to `getTextWidth`, we cache the width we compute. * This method is similar to ``getFastTextWidth`` but expects the font size * parameter to be a string. + * * @param textElement An SVG 'text' element. * @param fontSize The font size to use. * @param fontWeight The font weight to use. * @param fontFamily The font family to use. - * @return Width of element. + * @returns Width of element. * @alias Blockly.utils.dom.getFastTextWidthWithSizeString */ export function getFastTextWidthWithSizeString( @@ -360,11 +379,12 @@ export function getFastTextWidthWithSizeString( /** * Measure a font's metrics. The height and baseline values. + * * @param text Text to measure the font dimensions of. * @param fontSize The font size to use. * @param fontWeight The font weight to use. * @param fontFamily The font family to use. - * @return Font measurements. + * @returns Font measurements. * @alias Blockly.utils.dom.measureFontMetrics */ export function measureFontMetrics( diff --git a/core/utils/idgenerator.ts b/core/utils/idgenerator.ts index ac016000b..92b580fc9 100644 --- a/core/utils/idgenerator.ts +++ b/core/utils/idgenerator.ts @@ -6,6 +6,7 @@ /** * Generators for unique IDs. + * * @namespace Blockly.utils.idGenerator */ import * as goog from '../../closure/goog/goog.js'; @@ -15,6 +16,7 @@ goog.declareModuleId('Blockly.utils.idGenerator'); /** * Namespace object for internal implementations we want to be able to * stub in tests. + * * @ignore */ const internal = {}; @@ -31,7 +33,7 @@ let nextId = 0; * For UUIDs use genUid (below) instead; this ID generator should * primarily be used for IDs that end up in the DOM. * - * @return The next unique identifier. + * @returns The next unique identifier. * @alias Blockly.utils.idGenerator.getNextUniqueId */ export function getNextUniqueId(): string { @@ -51,7 +53,8 @@ const soup = '!#$%()*+,-./:;=?@[]^_`{|}~' + /** * Generate a random unique ID. This should be globally unique. * 87 characters ^ 20 length > 128 bits (better than a UUID). - * @return A globally unique ID string. + * + * @returns A globally unique ID string. */ // AnyDuringMigration because: Property 'genUid' does not exist on type '{}'. (internal as AnyDuringMigration).genUid = function(): string { @@ -66,8 +69,9 @@ const soup = '!#$%()*+,-./:;=?@[]^_`{|}~' + /** * Generate a random unique ID. + * * @see internal.genUid - * @return A globally unique ID string. + * @returns A globally unique ID string. * @alias Blockly.utils.idGenerator.genUid */ export function genUid(): string { diff --git a/core/utils/keycodes.ts b/core/utils/keycodes.ts index bb6cafd47..49aa8f8d7 100644 --- a/core/utils/keycodes.ts +++ b/core/utils/keycodes.ts @@ -8,6 +8,7 @@ * Constant declarations for common key codes. * These methods are not specific to Blockly, and could be factored out into * a JavaScript framework such as Closure. + * * @namespace Blockly.utils.KeyCodes */ import * as goog from '../../closure/goog/goog.js'; diff --git a/core/utils/math.ts b/core/utils/math.ts index 0b6040694..c92749aa5 100644 --- a/core/utils/math.ts +++ b/core/utils/math.ts @@ -8,6 +8,7 @@ * Utility methods for math. * These methods are not specific to Blockly, and could be factored out into * a JavaScript framework such as Closure. + * * @namespace Blockly.utils.math */ import * as goog from '../../closure/goog/goog.js'; @@ -17,8 +18,9 @@ goog.declareModuleId('Blockly.utils.math'); /** * Converts degrees to radians. * Copied from Closure's goog.math.toRadians. + * * @param angleDegrees Angle in degrees. - * @return Angle in radians. + * @returns Angle in radians. * @alias Blockly.utils.math.toRadians */ export function toRadians(angleDegrees: number): number { @@ -28,8 +30,9 @@ export function toRadians(angleDegrees: number): number { /** * Converts radians to degrees. * Copied from Closure's goog.math.toDegrees. + * * @param angleRadians Angle in radians. - * @return Angle in degrees. + * @returns Angle in degrees. * @alias Blockly.utils.math.toDegrees */ export function toDegrees(angleRadians: number): number { @@ -38,10 +41,11 @@ export function toDegrees(angleRadians: number): number { /** * Clamp the provided number between the lower bound and the upper bound. + * * @param lowerBound The desired lower bound. * @param number The number to clamp. * @param upperBound The desired upper bound. - * @return The clamped number. + * @returns The clamped number. * @alias Blockly.utils.math.clamp */ export function clamp( diff --git a/core/utils/metrics.ts b/core/utils/metrics.ts index 4d80391b9..495e017b8 100644 --- a/core/utils/metrics.ts +++ b/core/utils/metrics.ts @@ -6,6 +6,7 @@ /** * Workspace metrics definitions. + * * @namespace Blockly.utils.Metrics */ import * as goog from '../../closure/goog/goog.js'; diff --git a/core/utils/object.ts b/core/utils/object.ts index 9c41b473c..42cb59c22 100644 --- a/core/utils/object.ts +++ b/core/utils/object.ts @@ -6,6 +6,7 @@ /** * Utility methods for objects. + * * @namespace Blockly.utils.object */ import * as goog from '../../closure/goog/goog.js'; @@ -16,6 +17,7 @@ import * as deprecation from './deprecation.js'; /** * Inherit the prototype methods from one constructor into another. + * * @param childCtor Child class. * @param parentCtor Parent class. * @suppress {strictMissingProperties} superClass_ is not defined on Function. @@ -42,6 +44,7 @@ export function inherits(childCtor: Function, parentCtor: Function) { /** * Copies all the members of a source object to a target object. + * * @param target Target. * @param source Source. * @alias Blockly.utils.object.mixin @@ -56,9 +59,10 @@ export function mixin(target: AnyDuringMigration, source: AnyDuringMigration) { /** * Complete a deep merge of all members of a source object with a target object. + * * @param target Target. * @param source Source. - * @return The resulting object. + * @returns The resulting object. * @alias Blockly.utils.object.deepMerge */ export function deepMerge( @@ -76,8 +80,9 @@ export function deepMerge( /** * Returns an array of a given object's own enumerable property values. + * * @param obj Object containing values. - * @return Array of values. + * @returns Array of values. * @alias Blockly.utils.object.values */ export function values(obj: AnyDuringMigration): AnyDuringMigration[] { diff --git a/core/utils/parsing.ts b/core/utils/parsing.ts index 7aeebdf90..1034bfa45 100644 --- a/core/utils/parsing.ts +++ b/core/utils/parsing.ts @@ -18,11 +18,12 @@ import * as colourUtils from './colour.js'; /** * Internal implementation of the message reference and interpolation token * parsing used by tokenizeInterpolation() and replaceMessageReferences(). + * * @param message Text which might contain string table references and * interpolation tokens. * @param parseInterpolationTokens Option to parse numeric * interpolation tokens (%1, %2, ...) when true. - * @return Array of strings and numbers. + * @returns Array of strings and numbers. */ function tokenizeInterpolationInternal( message: string, parseInterpolationTokens: boolean): (string|number)[] { @@ -162,9 +163,10 @@ function tokenizeInterpolationInternal( * %{BKY_MY_MSG} will both be replaced with the value in * Msg['MY_MSG']). Percentage sign characters '%' may be self-escaped * (e.g., '%%'). + * * @param message Text which might contain string table references and * interpolation tokens. - * @return Array of strings and numbers. + * @returns Array of strings and numbers. * @alias Blockly.utils.parsing.tokenizeInterpolation */ export function tokenizeInterpolation(message: string): (string|number)[] { @@ -175,9 +177,10 @@ export function tokenizeInterpolation(message: string): (string|number)[] { * Replaces string table references in a message, if the message is a string. * For example, "%{bky_my_msg}" and "%{BKY_MY_MSG}" will both be replaced with * the value in Msg['MY_MSG']. + * * @param message Message, which may be a string that contains * string table references. - * @return String with message references replaced. + * @returns String with message references replaced. * @alias Blockly.utils.parsing.replaceMessageReferences */ export function replaceMessageReferences(message: string| @@ -194,8 +197,9 @@ export function replaceMessageReferences(message: string| /** * Validates that any %{MSG_KEY} references in the message refer to keys of * the Msg string table. + * * @param message Text which might contain string table references. - * @return True if all message references have matching values. + * @returns True if all message references have matching values. * Otherwise, false. * @alias Blockly.utils.parsing.checkMessageReferences */ @@ -222,9 +226,10 @@ export function checkMessageReferences(message: string): boolean { /** * Parse a block colour from a number or string, as provided in a block * definition. + * * @param colour HSV hue value (0 to 360), #RRGGBB string, * or a message reference string pointing to one of those two values. - * @return An object containing the colour as + * @returns An object containing the colour as * a #RRGGBB string, and the hue if the input was an HSV hue value. * @throws {Error} If the colour cannot be parsed. * @alias Blockly.utils.parsing.parseBlockColour diff --git a/core/utils/rect.ts b/core/utils/rect.ts index 8ac77e017..702c01c0a 100644 --- a/core/utils/rect.ts +++ b/core/utils/rect.ts @@ -8,6 +8,7 @@ * Utility methods for rectangle manipulation. * These methods are not specific to Blockly, and could be factored out into * a JavaScript framework such as Closure. + * * @class */ import * as goog from '../../closure/goog/goog.js'; @@ -16,6 +17,7 @@ goog.declareModuleId('Blockly.utils.Rect'); /** * Class for representing rectangular regions. + * * @alias Blockly.utils.Rect */ export class Rect { @@ -35,7 +37,7 @@ export class Rect { * * @param x The x coordinate to test for containment. * @param y The y coordinate to test for containment. - * @return Whether this rectangle contains given coordinate. + * @returns Whether this rectangle contains given coordinate. */ contains(x: number, y: number): boolean { return x >= this.left && x <= this.right && y >= this.top && @@ -45,8 +47,9 @@ export class Rect { /** * Tests whether this rectangle intersects the provided rectangle. * Assumes that the coordinate system increases going down and left. + * * @param other The other rectangle to check for intersection with. - * @return Whether this rectangle intersects the provided rectangle. + * @returns Whether this rectangle intersects the provided rectangle. */ intersects(other: Rect): boolean { return !( diff --git a/core/utils/size.ts b/core/utils/size.ts index 0a671b342..ae0f6d7a0 100644 --- a/core/utils/size.ts +++ b/core/utils/size.ts @@ -8,6 +8,7 @@ * Utility methods for size calculation. * These methods are not specific to Blockly, and could be factored out into * a JavaScript framework such as Closure. + * * @class */ import * as goog from '../../closure/goog/goog.js'; @@ -16,6 +17,7 @@ goog.declareModuleId('Blockly.utils.Size'); /** * Class for representing sizes consisting of a width and height. + * * @alias Blockly.utils.Size */ export class Size { @@ -28,9 +30,10 @@ export class Size { /** * Compares sizes for equality. + * * @param a A Size. * @param b A Size. - * @return True iff the sizes have equal widths and equal heights, or if both + * @returns True iff the sizes have equal widths and equal heights, or if both * are null. */ static equals(a: Size|null, b: Size|null): boolean { diff --git a/core/utils/string.ts b/core/utils/string.ts index 3530e4c75..c95def9ae 100644 --- a/core/utils/string.ts +++ b/core/utils/string.ts @@ -8,6 +8,7 @@ * Utility methods for string manipulation. * These methods are not specific to Blockly, and could be factored out into * a JavaScript framework such as Closure. + * * @namespace Blockly.utils.string */ import * as goog from '../../closure/goog/goog.js'; @@ -19,9 +20,10 @@ import * as deprecation from './deprecation.js'; /** * Fast prefix-checker. * Copied from Closure's goog.string.startsWith. + * * @param str The string to check. * @param prefix A string to look for at the start of `str`. - * @return True if `str` begins with `prefix`. + * @returns True if `str` begins with `prefix`. * @alias Blockly.utils.string.startsWith * @deprecated April 2022. Use built-in string.startsWith. */ @@ -34,8 +36,9 @@ export function startsWith(str: string, prefix: string): boolean { /** * Given an array of strings, return the length of the shortest one. + * * @param array Array of strings. - * @return Length of shortest string. + * @returns Length of shortest string. * @alias Blockly.utils.string.shortestStringLength */ export function shortestStringLength(array: string[]): number { @@ -52,9 +55,10 @@ export function shortestStringLength(array: string[]): number { /** * Given an array of strings, return the length of the common prefix. * Words may not be split. Any space after a word is included in the length. + * * @param array Array of strings. * @param opt_shortest Length of shortest string. - * @return Length of common prefix. + * @returns Length of common prefix. * @alias Blockly.utils.string.commonWordPrefix */ export function commonWordPrefix( @@ -90,9 +94,10 @@ export function commonWordPrefix( /** * Given an array of strings, return the length of the common suffix. * Words may not be split. Any space after a word is included in the length. + * * @param array Array of strings. * @param opt_shortest Length of shortest string. - * @return Length of common suffix. + * @returns Length of common suffix. * @alias Blockly.utils.string.commonWordSuffix */ export function commonWordSuffix( @@ -127,9 +132,10 @@ export function commonWordSuffix( /** * Wrap text to the specified width. + * * @param text Text to wrap. * @param limit Width to wrap each line. - * @return Wrapped text. + * @returns Wrapped text. * @alias Blockly.utils.string.wrap */ export function wrap(text: string, limit: number): string { @@ -142,9 +148,10 @@ export function wrap(text: string, limit: number): string { /** * Wrap single line of text to the specified width. + * * @param text Text to wrap. * @param limit Width to wrap each line. - * @return Wrapped text. + * @returns Wrapped text. */ function wrapLine(text: string, limit: number): string { if (text.length <= limit) { @@ -191,10 +198,11 @@ function wrapLine(text: string, limit: number): string { /** * Compute a score for how good the wrapping is. + * * @param words Array of each word. * @param wordBreaks Array of line breaks. * @param limit Width to wrap each line. - * @return Larger the better. + * @returns Larger the better. */ function wrapScore( words: string[], wordBreaks: boolean[], limit: number): number { @@ -243,10 +251,11 @@ function wrapScore( /** * Mutate the array of line break locations until an optimal solution is found. * No line breaks are added or deleted, they are simply moved around. + * * @param words Array of each word. * @param wordBreaks Array of line breaks. * @param limit Width to wrap each line. - * @return New array of optimal line breaks. + * @returns New array of optimal line breaks. */ function wrapMutate( words: string[], wordBreaks: boolean[], limit: number): boolean[] { @@ -276,9 +285,10 @@ function wrapMutate( /** * Reassemble the array of words into text, with the specified line breaks. + * * @param words Array of each word. * @param wordBreaks Array of line breaks. - * @return Plain text. + * @returns Plain text. */ function wrapToText(words: string[], wordBreaks: boolean[]): string { const text = []; @@ -293,8 +303,9 @@ function wrapToText(words: string[], wordBreaks: boolean[]): string { /** * Is the given string a number (includes negative and decimals). + * * @param str Input string. - * @return True if number, false otherwise. + * @returns True if number, false otherwise. * @alias Blockly.utils.string.isNumber */ export function isNumber(str: string): boolean { diff --git a/core/utils/style.ts b/core/utils/style.ts index 830566610..5ac1bdba9 100644 --- a/core/utils/style.ts +++ b/core/utils/style.ts @@ -8,6 +8,7 @@ * Utilities for element styles. * These methods are not specific to Blockly, and could be factored out into * a JavaScript framework such as Closure. + * * @namespace Blockly.utils.style */ import * as goog from '../../closure/goog/goog.js'; @@ -21,8 +22,9 @@ import {Size} from './size.js'; /** * Gets the height and width of an element. * Similar to Closure's goog.style.getSize + * * @param element Element to get size of. - * @return Object with width/height properties. + * @returns Object with width/height properties. * @alias Blockly.utils.style.getSize */ export function getSize(element: Element): Size { @@ -31,6 +33,8 @@ export function getSize(element: Element): Size { /** * Private version of getSize for stubbing in tests. + * + * @param element */ function getSizeInternal(element: Element): Size { if (getStyle(element, 'display') !== 'none') { @@ -61,8 +65,9 @@ function getSizeInternal(element: Element): Size { /** * Gets the height and width of an element when the display is not none. + * * @param element Element to get size of. - * @return Object with width/height properties. + * @returns Object with width/height properties. */ function getSizeWithDisplay(element: Element): Size { const offsetWidth = (element as HTMLElement).offsetWidth; @@ -81,7 +86,7 @@ function getSizeWithDisplay(element: Element): Size { * * @param element Element to get style of. * @param style Property to get (must be camelCase, not CSS-style). - * @return Style value. + * @returns Style value. */ function getStyle(element: Element, style: string): string { // AnyDuringMigration because: Property 'style' does not exist on type @@ -102,7 +107,7 @@ function getStyle(element: Element, style: string): string { * * @param element Element to get style of. * @param property Property to get (camel-case). - * @return Style value. + * @returns Style value. * @alias Blockly.utils.style.getComputedStyle */ export function getComputedStyle(element: Element, property: string): string { @@ -127,7 +132,7 @@ export function getComputedStyle(element: Element, property: string): string { * * @param element Element to get style of. * @param style Property to get (camel-case). - * @return Style value. + * @returns Style value. * @alias Blockly.utils.style.getCascadedStyle */ export function getCascadedStyle(element: Element, style: string): string { @@ -142,8 +147,9 @@ export function getCascadedStyle(element: Element, style: string): string { /** * Returns a Coordinate object relative to the top-left of the HTML document. * Similar to Closure's goog.style.getPageOffset + * * @param el Element to get the page offset for. - * @return The page offset. + * @returns The page offset. * @alias Blockly.utils.style.getPageOffset */ export function getPageOffset(el: Element): Coordinate { @@ -165,7 +171,8 @@ export function getPageOffset(el: Element): Coordinate { /** * Calculates the viewport coordinates relative to the document. * Similar to Closure's goog.style.getViewportPageOffset - * @return The page offset of the viewport. + * + * @returns The page offset of the viewport. * @alias Blockly.utils.style.getViewportPageOffset */ export function getViewportPageOffset(): Coordinate { @@ -200,7 +207,7 @@ export function setElementShown(el: Element, isShown: AnyDuringMigration) { * Copied from Closure's goog.style.isRightToLeft * * @param el The element to test. - * @return True for right to left, false for left to right. + * @returns True for right to left, false for left to right. * @alias Blockly.utils.style.isRightToLeft */ export function isRightToLeft(el: Element): boolean { @@ -210,8 +217,9 @@ export function isRightToLeft(el: Element): boolean { /** * Gets the computed border widths (on all sides) in pixels * Copied from Closure's goog.style.getBorderBox + * * @param element The element to get the border widths for. - * @return The computed border widths. + * @returns The computed border widths. * @alias Blockly.utils.style.getBorderBox */ export function getBorderBox(element: Element): Rect { @@ -256,7 +264,7 @@ export function scrollIntoContainerView( * scroll element will be used. * @param opt_center Whether to center the element in the container. * Defaults to false. - * @return The new scroll position of the container. + * @returns The new scroll position of the container. * @alias Blockly.utils.style.getContainerOffsetToScrollInto */ export function getContainerOffsetToScrollInto( diff --git a/core/utils/svg.ts b/core/utils/svg.ts index c36b85964..798505351 100644 --- a/core/utils/svg.ts +++ b/core/utils/svg.ts @@ -7,6 +7,7 @@ /** * Defines the Svg class. Its constants enumerate * all SVG tag names used by Blockly. + * * @class */ import * as goog from '../../closure/goog/goog.js'; @@ -15,6 +16,7 @@ goog.declareModuleId('Blockly.utils.Svg'); /** * A name with the type of the SVG element stored in the generic. + * * @alias Blockly.utils.Svg */ export class Svg<_T> { @@ -75,7 +77,8 @@ export class Svg<_T> { /** * Returns the SVG element tag name. - * @return The name. + * + * @returns The name. */ toString(): string { return this.tagName; diff --git a/core/utils/svg_math.ts b/core/utils/svg_math.ts index d03840236..c9bac3240 100644 --- a/core/utils/svg_math.ts +++ b/core/utils/svg_math.ts @@ -6,6 +6,7 @@ /** * Utility methods realted to figuring out positions of SVG elements. + * * @namespace Blockly.utils.svgMath */ import * as goog from '../../closure/goog/goog.js'; @@ -41,8 +42,9 @@ const XY_STYLE_REGEX: RegExp = /** * Return the coordinates of the top-left corner of this element relative to * its parent. Only for SVG elements and children (e.g. rect, g, path). + * * @param element SVG element to find the coordinates of. - * @return Object with .x and .y properties. + * @returns Object with .x and .y properties. * @alias Blockly.utils.svgMath.getRelativeXY */ export function getRelativeXY(element: Element): Coordinate { @@ -86,9 +88,10 @@ export function getRelativeXY(element: Element): Coordinate { /** * Return the coordinates of the top-left corner of this element relative to * the div Blockly was injected into. + * * @param element SVG element to find the coordinates of. If this is not a child * of the div Blockly was injected into, the behaviour is undefined. - * @return Object with .x and .y properties. + * @returns Object with .x and .y properties. * @alias Blockly.utils.svgMath.getInjectionDivXY */ export function getInjectionDivXY(element: Element): Coordinate { @@ -110,7 +113,8 @@ export function getInjectionDivXY(element: Element): Coordinate { /** * Check if 3D transforms are supported by adding an element * and attempting to set the property. - * @return True if 3D transforms are supported. + * + * @returns True if 3D transforms are supported. * @alias Blockly.utils.svgMath.is3dSupported */ export function is3dSupported(): boolean { @@ -170,7 +174,8 @@ export function is3dSupported(): boolean { /** * Get the position of the current viewport in window coordinates. This takes * scroll into account. - * @return An object containing window width, height, and scroll position in + * + * @returns An object containing window width, height, and scroll position in * window coordinates. * @alias Blockly.utils.svgMath.getViewportBBox * @internal @@ -186,7 +191,8 @@ export function getViewportBBox(): Rect { /** * Gets the document scroll distance as a coordinate object. * Copied from Closure's goog.dom.getDocumentScroll. - * @return Object with values 'x' and 'y'. + * + * @returns Object with values 'x' and 'y'. * @alias Blockly.utils.svgMath.getDocumentScroll */ export function getDocumentScroll(): Coordinate { @@ -204,10 +210,11 @@ export function getDocumentScroll(): Coordinate { /** * Converts screen coordinates to workspace coordinates. + * * @param ws The workspace to find the coordinates on. * @param screenCoordinates The screen coordinates to be converted to workspace * coordinates - * @return The workspace coordinates. + * @returns The workspace coordinates. * @alias Blockly.utils.svgMath.screenToWsCoordinates */ export function screenToWsCoordinates( @@ -240,8 +247,9 @@ export function screenToWsCoordinates( /** * Returns the dimensions of the specified SVG image. + * * @param svg SVG image. - * @return Contains width and height properties. + * @returns Contains width and height properties. * @deprecated Use workspace.getCachedParentSvgSize. (2021 March 5) * @alias Blockly.utils.svgMath.svgSize */ diff --git a/core/utils/svg_paths.ts b/core/utils/svg_paths.ts index e85e8aa7f..d87766604 100644 --- a/core/utils/svg_paths.ts +++ b/core/utils/svg_paths.ts @@ -6,6 +6,7 @@ /** * Methods for creating parts of SVG path strings. See + * * @namespace Blockly.utils.svgPaths */ import * as goog from '../../closure/goog/goog.js'; @@ -17,9 +18,10 @@ goog.declareModuleId('Blockly.utils.svgPaths'); * the coordinate is relative or absolute. The result has leading * and trailing spaces, and separates the x and y coordinates with a comma but * no space. + * * @param x The x coordinate. * @param y The y coordinate. - * @return A string of the format ' x,y ' + * @returns A string of the format ' x,y ' * @alias Blockly.utils.svgPaths.point */ export function point(x: number, y: number): string { @@ -30,12 +32,13 @@ export function point(x: number, y: number): string { * Draw a cubic or quadratic curve. See * developer.mozilla.org/en-US/docs/Web/SVG/Attribute/d#Cubic_B%C3%A9zier_Curve * These coordinates are unitless and hence in the user coordinate system. + * * @param command The command to use. * Should be one of: c, C, s, S, q, Q. * @param points An array containing all of the points to pass to the curve * command, in order. The points are represented as strings of the format ' * x, y '. - * @return A string defining one or more Bezier curves. See the MDN + * @returns A string defining one or more Bezier curves. See the MDN * documentation for exact format. * @alias Blockly.utils.svgPaths.curve */ @@ -48,9 +51,10 @@ export function curve(command: string, points: string[]): string { * The coordinates are absolute. * These coordinates are unitless and hence in the user coordinate system. * See developer.mozilla.org/en-US/docs/Web/SVG/Tutorial/Paths#Line_commands + * * @param x The absolute x coordinate. * @param y The absolute y coordinate. - * @return A string of the format ' M x,y ' + * @returns A string of the format ' M x,y ' * @alias Blockly.utils.svgPaths.moveTo */ export function moveTo(x: number, y: number): string { @@ -62,9 +66,10 @@ export function moveTo(x: number, y: number): string { * Coordinates are relative. * These coordinates are unitless and hence in the user coordinate system. * See developer.mozilla.org/en-US/docs/Web/SVG/Tutorial/Paths#Line_commands + * * @param dx The relative x coordinate. * @param dy The relative y coordinate. - * @return A string of the format ' m dx,dy ' + * @returns A string of the format ' m dx,dy ' * @alias Blockly.utils.svgPaths.moveBy */ export function moveBy(dx: number, dy: number): string { @@ -76,9 +81,10 @@ export function moveBy(dx: number, dy: number): string { * point shifted by dx along the x-axis and dy along the y-axis. * These coordinates are unitless and hence in the user coordinate system. * See developer.mozilla.org/en-US/docs/Web/SVG/Tutorial/Paths#Line_commands + * * @param dx The relative x coordinate. * @param dy The relative y coordinate. - * @return A string of the format ' l dx,dy ' + * @returns A string of the format ' l dx,dy ' * @alias Blockly.utils.svgPaths.lineTo */ export function lineTo(dx: number, dy: number): string { @@ -90,9 +96,10 @@ export function lineTo(dx: number, dy: number): string { * equivalent to a series of 'l' commands. * These coordinates are unitless and hence in the user coordinate system. * See developer.mozilla.org/en-US/docs/Web/SVG/Tutorial/Paths#Line_commands + * * @param points An array containing all of the points to draw lines to, in * order. The points are represented as strings of the format ' dx,dy '. - * @return A string of the format ' l (dx,dy)+ ' + * @returns A string of the format ' l (dx,dy)+ ' * @alias Blockly.utils.svgPaths.line */ export function line(points: string[]): string { @@ -105,11 +112,12 @@ export function line(points: string[]): string { * relative or absolute. * These coordinates are unitless and hence in the user coordinate system. * See developer.mozilla.org/en-US/docs/Web/SVG/Attribute/d#LineTo_path_commands + * * @param command The command to prepend to the coordinate. This should be one * of: V, v, H, h. * @param val The coordinate to pass to the command. It may be absolute or * relative. - * @return A string of the format ' command val ' + * @returns A string of the format ' command val ' * @alias Blockly.utils.svgPaths.lineOnAxis */ export function lineOnAxis(command: string, val: number): string { @@ -120,13 +128,14 @@ export function lineOnAxis(command: string, val: number): string { * Draw an elliptical arc curve. * These coordinates are unitless and hence in the user coordinate system. * See developer.mozilla.org/en-US/docs/Web/SVG/Attribute/d#Elliptical_Arc_Curve + * * @param command The command string. Either 'a' or 'A'. * @param flags The flag string. See the MDN documentation for a description * and examples. * @param radius The radius of the arc to draw. * @param point The point to move the cursor to after drawing the arc, specified * either in absolute or relative coordinates depending on the command. - * @return A string of the format 'command radius radius flags point' + * @returns A string of the format 'command radius radius flags point' * @alias Blockly.utils.svgPaths.arc */ export function arc( diff --git a/core/utils/toolbox.ts b/core/utils/toolbox.ts index 1d00e8ac9..e14151ccc 100644 --- a/core/utils/toolbox.ts +++ b/core/utils/toolbox.ts @@ -6,6 +6,7 @@ /** * Utility functions for the toolbox and flyout. + * * @namespace Blockly.utils.toolbox */ import * as goog from '../../closure/goog/goog.js'; @@ -28,6 +29,7 @@ import * as userAgent from './useragent.js'; /** * The information needed to create a block in the toolbox. * Note that disabled has a different type for backwards compatibility. + * * @alias Blockly.utils.toolbox.BlockInfo */ export interface BlockInfo { @@ -52,6 +54,7 @@ export interface BlockInfo { /** * The information needed to create a separator in the toolbox. + * * @alias Blockly.utils.toolbox.SeparatorInfo */ export interface SeparatorInfo { @@ -63,6 +66,7 @@ export interface SeparatorInfo { /** * The information needed to create a button in the toolbox. + * * @alias Blockly.utils.toolbox.ButtonInfo */ export interface ButtonInfo { @@ -73,6 +77,7 @@ export interface ButtonInfo { /** * The information needed to create a label in the toolbox. + * * @alias Blockly.utils.toolbox.LabelInfo */ export interface LabelInfo { @@ -83,12 +88,14 @@ export interface LabelInfo { /** * The information needed to create either a button or a label in the flyout. + * * @alias Blockly.utils.toolbox.ButtonOrLabelInfo */ export type ButtonOrLabelInfo = ButtonInfo|LabelInfo; /** * The information needed to create a category in the toolbox. + * * @alias Blockly.utils.toolbox.StaticCategoryInfo */ export interface StaticCategoryInfo { @@ -104,6 +111,7 @@ export interface StaticCategoryInfo { /** * The information needed to create a custom category. + * * @alias Blockly.utils.toolbox.DynamicCategoryInfo */ export interface DynamicCategoryInfo { @@ -118,18 +126,21 @@ export interface DynamicCategoryInfo { /** * The information needed to create either a dynamic or static category. + * * @alias Blockly.utils.toolbox.CategoryInfo */ export type CategoryInfo = StaticCategoryInfo|DynamicCategoryInfo; /** * Any information that can be used to create an item in the toolbox. + * * @alias Blockly.utils.toolbox.ToolboxItemInfo */ export type ToolboxItemInfo = FlyoutItemInfo|StaticCategoryInfo; /** * All the different types that can be displayed in a flyout. + * * @alias Blockly.utils.toolbox.FlyoutItemInfo */ export type FlyoutItemInfo = @@ -137,6 +148,7 @@ export type FlyoutItemInfo = /** * The JSON definition of a toolbox. + * * @alias Blockly.utils.toolbox.ToolboxInfo */ export interface ToolboxInfo { @@ -146,18 +158,21 @@ export interface ToolboxInfo { /** * An array holding flyout items. + * * @alias Blockly.utils.toolbox.FlyoutItemInfoArray */ export type FlyoutItemInfoArray = FlyoutItemInfo[]; /** * All of the different types that can create a toolbox. + * * @alias Blockly.utils.toolbox.ToolboxDefinition */ export type ToolboxDefinition = Node|ToolboxInfo|string; /** * All of the different types that can be used to show items in a flyout. + * * @alias Blockly.utils.toolbox.FlyoutDefinition */ export type FlyoutDefinition = FlyoutItemInfoArray|NodeList|ToolboxInfo|Node[]; @@ -178,6 +193,7 @@ const FLYOUT_TOOLBOX_KIND = 'flyoutToolbox'; /** * Position of the toolbox and/or flyout relative to the workspace. + * * @alias Blockly.utils.toolbox.Position */ export enum Position { @@ -189,8 +205,9 @@ export enum Position { /** * Converts the toolbox definition into toolbox JSON. + * * @param toolboxDef The definition of the toolbox in one of its many forms. - * @return Object holding information for creating a toolbox. + * @returns Object holding information for creating a toolbox. * @alias Blockly.utils.toolbox.convertToolboxDefToJson * @internal */ @@ -214,6 +231,7 @@ export function convertToolboxDefToJson(toolboxDef: ToolboxDefinition| /** * Validates the toolbox JSON fields have been set correctly. + * * @param toolboxJson Object holding information for creating a toolbox. * @throws {Error} if the toolbox is not the correct format. */ @@ -237,8 +255,9 @@ function validateToolbox(toolboxJson: ToolboxInfo) { /** * Converts the flyout definition into a list of flyout items. + * * @param flyoutDef The definition of the flyout in one of its many forms. - * @return A list of flyout items. + * @returns A list of flyout items. * @alias Blockly.utils.toolbox.convertFlyoutDefToJsonArray * @internal */ @@ -268,8 +287,9 @@ export function convertFlyoutDefToJsonArray(flyoutDef: FlyoutDefinition| /** * Whether or not the toolbox definition has categories. + * * @param toolboxJson Object holding information for creating a toolbox. - * @return True if the toolbox has categories. + * @returns True if the toolbox has categories. * @alias Blockly.utils.toolbox.hasCategories * @internal */ @@ -279,6 +299,8 @@ export function hasCategories(toolboxJson: ToolboxInfo|null): boolean { /** * Private version of hasCategories for stubbing in tests. + * + * @param toolboxJson */ function hasCategoriesInternal(toolboxJson: ToolboxInfo|null): boolean { if (!toolboxJson) { @@ -298,8 +320,9 @@ function hasCategoriesInternal(toolboxJson: ToolboxInfo|null): boolean { /** * Whether or not the category is collapsible. + * * @param categoryInfo Object holing information for creating a category. - * @return True if the category has subcategories. + * @returns True if the category has subcategories. * @alias Blockly.utils.toolbox.isCategoryCollapsible * @internal */ @@ -318,8 +341,9 @@ export function isCategoryCollapsible(categoryInfo: CategoryInfo): boolean { /** * Parses the provided toolbox definition into a consistent format. + * * @param toolboxDef The definition of the toolbox in one of its many forms. - * @return Object holding information for creating a toolbox. + * @returns Object holding information for creating a toolbox. */ function convertToToolboxJson(toolboxDef: Node): ToolboxInfo { const contents = xmlToJsonArray(toolboxDef as Node | Node[]); @@ -332,8 +356,9 @@ function convertToToolboxJson(toolboxDef: Node): ToolboxInfo { /** * Converts the xml for a toolbox to JSON. + * * @param toolboxDef The definition of the toolbox in one of its many forms. - * @return A list of objects in the toolbox. + * @returns A list of objects in the toolbox. */ function xmlToJsonArray(toolboxDef: Node|Node[]|NodeList): FlyoutItemInfoArray| ToolboxItemInfo[] { @@ -373,6 +398,7 @@ function xmlToJsonArray(toolboxDef: Node|Node[]|NodeList): FlyoutItemInfoArray| /** * Adds the attributes on the node to the given object. + * * @param node The node to copy the attributes from. * @param obj The object to copy the attributes to. */ @@ -394,8 +420,9 @@ function addAttributes(node: Node, obj: AnyDuringMigration) { /** * Parse the provided toolbox tree into a consistent DOM format. + * * @param toolboxDef DOM tree of blocks, or text representation of same. - * @return DOM tree of blocks, or null. + * @returns DOM tree of blocks, or null. * @alias Blockly.utils.toolbox.parseToolboxTree */ export function parseToolboxTree(toolboxDef: Element|null|string): Element| diff --git a/core/utils/useragent.ts b/core/utils/useragent.ts index daf5cd65f..273bc1497 100644 --- a/core/utils/useragent.ts +++ b/core/utils/useragent.ts @@ -8,6 +8,7 @@ * Useragent detection. * These methods are not specific to Blockly, and could be factored out into * a JavaScript framework such as Closure. + * * @namespace Blockly.utils.userAgent */ import * as goog from '../../closure/goog/goog.js'; @@ -48,8 +49,9 @@ rawUserAgent = raw; const rawUpper = rawUserAgent.toUpperCase(); /** * Case-insensitive test of whether name is in the useragent string. + * * @param name Name to test. - * @return True if name is present. + * @returns True if name is present. */ function has(name: string): boolean { return rawUpper.indexOf(name.toUpperCase()) !== -1; diff --git a/core/utils/xml.ts b/core/utils/xml.ts index f698095bd..7e701d12e 100644 --- a/core/utils/xml.ts +++ b/core/utils/xml.ts @@ -8,6 +8,7 @@ * XML element manipulation. * These methods are not specific to Blockly, and could be factored out into * a JavaScript framework such as Closure. + * * @namespace Blockly.utils.xml */ import * as goog from '../../closure/goog/goog.js'; @@ -16,6 +17,7 @@ goog.declareModuleId('Blockly.utils.xml'); /** * Namespace for Blockly's XML. + * * @alias Blockly.utils.xml.NAME_SPACE */ export const NAME_SPACE = 'https://developers.google.com/blockly/xml'; @@ -30,7 +32,8 @@ let xmlDocument: Document = globalThis['document']; /** * Get the document object to use for XML serialization. - * @return The document object. + * + * @returns The document object. * @alias Blockly.utils.xml.getDocument */ export function getDocument(): Document { @@ -39,6 +42,7 @@ export function getDocument(): Document { /** * Get the document object to use for XML serialization. + * * @param document The document object to use. * @alias Blockly.utils.xml.setDocument */ @@ -48,8 +52,9 @@ export function setDocument(document: Document) { /** * Create DOM element for XML. + * * @param tagName Name of DOM element. - * @return New DOM element. + * @returns New DOM element. * @alias Blockly.utils.xml.createElement */ export function createElement(tagName: string): Element { @@ -58,8 +63,9 @@ export function createElement(tagName: string): Element { /** * Create text element for XML. + * * @param text Text content. - * @return New DOM text node. + * @returns New DOM text node. * @alias Blockly.utils.xml.createTextNode */ export function createTextNode(text: string): Text { @@ -68,8 +74,9 @@ export function createTextNode(text: string): Text { /** * Converts an XML string into a DOM tree. + * * @param text XML string. - * @return The DOM document. + * @returns The DOM document. * @throws if XML doesn't parse. * @alias Blockly.utils.xml.textToDomDocument */ @@ -81,8 +88,9 @@ export function textToDomDocument(text: string): Document { /** * Converts a DOM structure into plain text. * Currently the text format is fairly ugly: all one line with no whitespace. + * * @param dom A tree of XML nodes. - * @return Text representation. + * @returns Text representation. * @alias Blockly.utils.xml.domToText */ export function domToText(dom: Node): string { diff --git a/core/variable_map.ts b/core/variable_map.ts index 03790e4bc..0750f14a0 100644 --- a/core/variable_map.ts +++ b/core/variable_map.ts @@ -6,6 +6,7 @@ /** * Object representing a map of variables and their types. + * * @class */ import * as goog from '../closure/goog/goog.js'; @@ -31,6 +32,7 @@ import type {Workspace} from './workspace.js'; * Class for a variable map. This contains a dictionary data structure with * variable types as keys and lists of variables as values. The list of * variables are the type indicated by the key. + * * @alias Blockly.VariableMap */ export class VariableMap { @@ -51,6 +53,7 @@ export class VariableMap { /* Begin functions for renaming variables. */ /** * Rename the given variable by updating its name in the variable map. + * * @param variable Variable to rename. * @param newName New variable name. * @internal @@ -77,6 +80,7 @@ export class VariableMap { /** * Rename a variable by updating its name in the variable map. Identify the * variable to rename with the given ID. + * * @param id ID of the variable to rename. * @param newName New variable name. */ @@ -92,6 +96,7 @@ export class VariableMap { /** * Update the name of the given variable and refresh all references to it. * The new name must not conflict with any existing variable names. + * * @param variable Variable to rename. * @param newName New variable name. * @param blocks The list of all blocks in the workspace. @@ -111,6 +116,7 @@ export class VariableMap { * variable. The two variables are coalesced into a single variable with the * ID of the existing variable that was already using newName. Refresh all * references to the variable. + * * @param variable Variable to rename. * @param newName New variable name. * @param conflictVar The variable that was already using newName. @@ -140,13 +146,14 @@ export class VariableMap { /* End functions for renaming variables. */ /** * Create a variable with a given name, optional type, and optional ID. + * * @param name The name of the variable. This must be unique across variables * and procedures. * @param opt_type The type of the variable like 'int' or 'string'. * Does not need to be unique. Field_variable can filter variables based * on their type. This will default to '' which is a specific type. * @param opt_id The unique ID of the variable. This will default to a UUID. - * @return The newly created variable. + * @returns The newly created variable. */ createVariable(name: string, opt_type?: string|null, opt_id?: string|null): VariableModel { @@ -182,6 +189,7 @@ export class VariableMap { /* Begin functions for variable deletion. */ /** * Delete a variable. + * * @param variable Variable to delete. */ deleteVariable(variable: VariableModel) { @@ -203,6 +211,7 @@ export class VariableMap { /** * Delete a variables by the passed in ID and all of its uses from this * workspace. May prompt the user for confirmation. + * * @param id ID of variable to delete. */ deleteVariableById(id: string) { @@ -246,6 +255,7 @@ export class VariableMap { /** * Deletes a variable and all of its uses from this workspace without asking * the user for confirmation. + * * @param variable Variable to delete. * @param uses An array of uses of the variable. * @internal @@ -270,10 +280,11 @@ export class VariableMap { /** * Find the variable by the given name and type and return it. Return null if * it is not found. + * * @param name The name to check for. * @param opt_type The type of the variable. If not provided it defaults to * the empty string, which is a specific type. - * @return The variable with the given name, or null if it was not found. + * @returns The variable with the given name, or null if it was not found. */ getVariable(name: string, opt_type?: string|null): VariableModel|null { const type = opt_type || ''; @@ -290,8 +301,9 @@ export class VariableMap { /** * Find the variable by the given ID and return it. Return null if not found. + * * @param id The ID to check for. - * @return The variable with the given ID. + * @returns The variable with the given ID. */ getVariableById(id: string): VariableModel|null { for (const [_key, variables] of this.variableMap) { @@ -307,8 +319,9 @@ export class VariableMap { /** * Get a list containing all of the variables of a specified type. If type is * null, return list of variables with empty string type. + * * @param type Type of the variables to find. - * @return The sought after variables of the passed in type. An empty array if + * @returns The sought after variables of the passed in type. An empty array if * none are found. */ getVariablesOfType(type: string|null): VariableModel[] { @@ -323,10 +336,11 @@ export class VariableMap { /** * Return all variable and potential variable types. This list always * contains the empty string. + * * @param ws The workspace used to look for potential variables. This can be * different than the workspace stored on this object if the passed in ws * is a flyout workspace. - * @return List of variable types. + * @returns List of variable types. * @internal */ getVariableTypes(ws: Workspace|null): string[] { @@ -344,7 +358,8 @@ export class VariableMap { /** * Return all variables of all types. - * @return List of variable models. + * + * @returns List of variable models. */ getAllVariables(): VariableModel[] { let allVariables: VariableModel[] = []; @@ -356,7 +371,8 @@ export class VariableMap { /** * Returns all of the variable names of all types. - * @return All of the variable names of all types. + * + * @returns All of the variable names of all types. */ getAllVariableNames(): string[] { return Array.from(this.variableMap.values()) @@ -366,8 +382,9 @@ export class VariableMap { /** * Find all the uses of a named variable. + * * @param id ID of the variable to find. - * @return Array of block usages. + * @returns Array of block usages. */ getVariableUsesById(id: string): Block[] { const uses = []; diff --git a/core/variables.ts b/core/variables.ts index 600b1bbc2..54698f555 100644 --- a/core/variables.ts +++ b/core/variables.ts @@ -6,6 +6,7 @@ /** * Utility functions for handling variables. + * * @namespace Blockly.Variables */ import * as goog from '../closure/goog/goog.js'; @@ -27,6 +28,7 @@ import * as Xml from './xml.js'; * variable blocks. * See also Blockly.Procedures.CATEGORY_NAME and * Blockly.VariablesDynamic.CATEGORY_NAME. + * * @alias Blockly.Variables.CATEGORY_NAME */ export const CATEGORY_NAME = 'VARIABLE'; @@ -36,8 +38,9 @@ export const CATEGORY_NAME = 'VARIABLE'; * For use by generators. * To get a list of all variables on a workspace, including unused variables, * call Workspace.getAllVariables. + * * @param ws The workspace to search for variables. - * @return Array of variable models. + * @returns Array of variable models. * @alias Blockly.Variables.allUsedVarModels */ export function allUsedVarModels(ws: Workspace): VariableModel[] { @@ -69,8 +72,9 @@ const ALL_DEVELOPER_VARS_WARNINGS_BY_BLOCK_TYPE: {[key: string]: boolean} = {}; * To declare developer variables, define the getDeveloperVariables function on * your block and return a list of variable names. * For use by generators. + * * @param workspace The workspace to search. - * @return A list of non-duplicated variable names. + * @returns A list of non-duplicated variable names. * @alias Blockly.Variables.allDeveloperVariables */ export function allDeveloperVariables(workspace: Workspace): string[] { @@ -104,8 +108,9 @@ export function allDeveloperVariables(workspace: Workspace): string[] { /** * Construct the elements (blocks and button) required by the flyout for the * variable category. + * * @param workspace The workspace containing variables. - * @return Array of XML elements. + * @returns Array of XML elements. * @alias Blockly.Variables.flyoutCategory */ export function flyoutCategory(workspace: WorkspaceSvg): Element[] { @@ -132,8 +137,9 @@ export function flyoutCategory(workspace: WorkspaceSvg): Element[] { /** * Construct the blocks required by the flyout for the variable category. + * * @param workspace The workspace containing variables. - * @return Array of XML block elements. + * @returns Array of XML block elements. * @alias Blockly.Variables.flyoutCategoryBlocks */ export function flyoutCategoryBlocks(workspace: Workspace): Element[] { @@ -204,8 +210,9 @@ export const VAR_LETTER_OPTIONS = 'ijkmnopqrstuvwxyzabcdefgh'; * generate single letter variable names in the range 'i' to 'z' to start with. * If no unique name is located it will try 'i' to 'z', 'a' to 'h', * then 'i2' to 'z2' etc. Skip 'l'. + * * @param workspace The workspace to be unique in. - * @return New variable name. + * @returns New variable name. * @alias Blockly.Variables.generateUniqueName */ export function generateUniqueName(workspace: Workspace): string { @@ -214,6 +221,8 @@ export function generateUniqueName(workspace: Workspace): string { /** * Private version of generateUniqueName for stubbing in tests. + * + * @param workspace */ function generateUniqueNameInternal(workspace: Workspace): string { return generateUniqueNameFromOptions( @@ -224,9 +233,10 @@ function generateUniqueNameInternal(workspace: Workspace): string { * Returns a unique name that is not present in the usedNames array. This * will try to generate single letter names in the range a -> z (skip l). It * will start with the character passed to startChar. + * * @param startChar The character to start the search at. * @param usedNames A list of all of the used names. - * @return A unique name that is not present in the usedNames array. + * @returns A unique name that is not present in the usedNames array. * @alias Blockly.Variables.generateUniqueNameFromOptions */ export function generateUniqueNameFromOptions( @@ -288,6 +298,10 @@ export function createVariableButtonHandler( opt_type?: string) { const type = opt_type || ''; // This function needs to be named so it can be called recursively. + /** + * + * @param defaultName + */ function promptAndCheckWithAlert(defaultName: AnyDuringMigration) { promptName(Msg['NEW_VARIABLE_TITLE'], defaultName, function(text) { if (text) { @@ -325,6 +339,7 @@ export function createVariableButtonHandler( * Opens a prompt that allows the user to enter a new name for a variable. * Triggers a rename if the new name is valid. Or re-prompts if there is a * collision. + * * @param workspace The workspace on which to rename the variable. * @param variable Variable to rename. * @param opt_callback A callback. It will be passed an acceptable new variable @@ -336,6 +351,10 @@ export function renameVariable( workspace: Workspace, variable: VariableModel, opt_callback?: (p1?: string|null) => AnyDuringMigration) { // This function needs to be named so it can be called recursively. + /** + * + * @param defaultName + */ function promptAndCheckWithAlert(defaultName: AnyDuringMigration) { const promptText = Msg['RENAME_VARIABLE_TITLE'].replace('%1', variable.name); @@ -369,6 +388,7 @@ export function renameVariable( /** * Prompt the user for a new variable name. + * * @param promptText The string of the prompt. * @param defaultText The default value to show in the prompt's field. * @param callback A callback. It will return the new variable name, or null if @@ -394,10 +414,11 @@ export function promptName( /** * Check whether there exists a variable with the given name but a different * type. + * * @param name The name to search for. * @param type The type to exclude from the search. * @param workspace The workspace to search for the variable. - * @return The variable with the given name and a different type, or null if + * @returns The variable with the given name and a different type, or null if * none was found. */ function nameUsedWithOtherType( @@ -415,9 +436,10 @@ function nameUsedWithOtherType( /** * Check whether there exists a variable with the given name of any type. + * * @param name The name to search for. * @param workspace The workspace to search for the variable. - * @return The variable with the given name, or null if none was found. + * @returns The variable with the given name, or null if none was found. * @alias Blockly.Variables.nameUsedWithAnyType */ export function nameUsedWithAnyType( @@ -435,8 +457,9 @@ export function nameUsedWithAnyType( /** * Generate DOM objects representing a variable field. + * * @param variableModel The variable model to represent. - * @return The generated DOM. + * @returns The generated DOM. * @alias Blockly.Variables.generateVariableFieldDom */ export function generateVariableFieldDom(variableModel: VariableModel): Element| @@ -456,12 +479,13 @@ export function generateVariableFieldDom(variableModel: VariableModel): Element| /** * Helper function to look up or create a variable on the given workspace. * If no variable exists, creates and returns it. + * * @param workspace The workspace to search for the variable. It may be a * flyout workspace or main workspace. * @param id The ID to use to look up or create the variable, or null. * @param opt_name The string to use to look up or create the variable. * @param opt_type The type to use to look up or create the variable. - * @return The variable corresponding to the given ID or name + type + * @returns The variable corresponding to the given ID or name + type * combination. * @alias Blockly.Variables.getOrCreateVariablePackage */ @@ -479,6 +503,7 @@ export function getOrCreateVariablePackage( * Look up a variable on the given workspace. * Always looks in the main workspace before looking in the flyout workspace. * Always prefers lookup by ID to lookup by name + type. + * * @param workspace The workspace to search for the variable. It may be a * flyout workspace or main workspace. * @param id The ID to use to look up the variable, or null. @@ -486,7 +511,7 @@ export function getOrCreateVariablePackage( * Only used if lookup by ID fails. * @param opt_type The type to use to look up the variable. * Only used if lookup by ID fails. - * @return The variable corresponding to the given ID or name + type + * @returns The variable corresponding to the given ID or name + type * combination, or null if not found. * @alias Blockly.Variables.getVariable */ @@ -523,12 +548,13 @@ export function getVariable( /** * Helper function to create a variable on the given workspace. + * * @param workspace The workspace in which to create the variable. It may be a * flyout workspace or main workspace. * @param id The ID to use to create the variable, or null. * @param opt_name The string to use to create the variable. * @param opt_type The type to use to create the variable. - * @return The variable corresponding to the given ID or name + type + * @returns The variable corresponding to the given ID or name + type * combination. */ function createVariable( @@ -561,10 +587,11 @@ function createVariable( * Helper function to get the list of variables that have been added to the * workspace after adding a new block, using the given list of variables that * were in the workspace before the new block was added. + * * @param workspace The workspace to inspect. * @param originalVariables The array of variables that existed in the workspace * before adding the new block. - * @return The new array of variables that were freshly added to the workspace + * @returns The new array of variables that were freshly added to the workspace * after creating the new block, or [] if no new variables were added to the * workspace. * @alias Blockly.Variables.getAddedVariables diff --git a/core/variables_dynamic.ts b/core/variables_dynamic.ts index 1ac5d67da..b29ee779b 100644 --- a/core/variables_dynamic.ts +++ b/core/variables_dynamic.ts @@ -27,16 +27,25 @@ import type {WorkspaceSvg} from './workspace_svg.js'; * variable blocks. * See also Blockly.Variables.CATEGORY_NAME and * Blockly.Procedures.CATEGORY_NAME. + * * @alias Blockly.VariablesDynamic.CATEGORY_NAME */ export const CATEGORY_NAME = 'VARIABLE_DYNAMIC'; +/** + * + * @param button + */ function stringButtonClickHandler(button: AnyDuringMigration) { Variables.createVariableButtonHandler( button.getTargetWorkspace(), undefined, 'String'); } // eslint-disable-next-line camelcase export const onCreateVariableButtonClick_String = stringButtonClickHandler; +/** + * + * @param button + */ function numberButtonClickHandler(button: AnyDuringMigration) { Variables.createVariableButtonHandler( button.getTargetWorkspace(), undefined, 'Number'); @@ -44,6 +53,10 @@ function numberButtonClickHandler(button: AnyDuringMigration) { // eslint-disable-next-line camelcase export const onCreateVariableButtonClick_Number = numberButtonClickHandler; +/** + * + * @param button + */ function colourButtonClickHandler(button: AnyDuringMigration) { Variables.createVariableButtonHandler( button.getTargetWorkspace(), undefined, 'Colour'); @@ -54,8 +67,9 @@ export const onCreateVariableButtonClick_Colour = colourButtonClickHandler; /** * Construct the elements (blocks and button) required by the flyout for the * variable category. + * * @param workspace The workspace containing variables. - * @return Array of XML elements. + * @returns Array of XML elements. * @alias Blockly.VariablesDynamic.flyoutCategory */ export function flyoutCategory(workspace: WorkspaceSvg): Element[] { @@ -89,8 +103,9 @@ export function flyoutCategory(workspace: WorkspaceSvg): Element[] { /** * Construct the blocks required by the flyout for the variable category. + * * @param workspace The workspace containing variables. - * @return Array of XML block elements. + * @returns Array of XML block elements. * @alias Blockly.VariablesDynamic.flyoutCategoryBlocks */ export function flyoutCategoryBlocks(workspace: Workspace): Element[] { diff --git a/core/warning.ts b/core/warning.ts index 4aef917aa..e917616c9 100644 --- a/core/warning.ts +++ b/core/warning.ts @@ -6,6 +6,7 @@ /** * Object representing a warning. + * * @class */ import * as goog from '../closure/goog/goog.js'; @@ -25,6 +26,7 @@ import {Svg} from './utils/svg.js'; /** * Class for a warning. + * * @alias Blockly.Warning */ export class Warning extends Icon { @@ -47,6 +49,7 @@ export class Warning extends Icon { /** * Draw the warning icon. + * * @param group The icon group. */ protected override drawIcon_(group: Element) { @@ -79,6 +82,7 @@ export class Warning extends Icon { /** * Show or hide the warning bubble. + * * @param visible True if the bubble should be visible. */ override setVisible(visible: boolean) { @@ -116,6 +120,7 @@ export class Warning extends Icon { /** * Set this warning's text. + * * @param text Warning text (or '' to delete). This supports linebreaks. * @param id An ID for this text entry to be able to maintain multiple * warnings. @@ -137,7 +142,8 @@ export class Warning extends Icon { /** * Get this warning's texts. - * @return All texts concatenated into one string. + * + * @returns All texts concatenated into one string. */ getText(): string { const allWarnings = []; diff --git a/core/widgetdiv.ts b/core/widgetdiv.ts index 1ede8077a..2642c4c44 100644 --- a/core/widgetdiv.ts +++ b/core/widgetdiv.ts @@ -8,6 +8,7 @@ * A div that floats on top of Blockly. This singleton contains * temporary HTML UI widgets that the user is currently interacting with. * E.g. text input areas, colour pickers, context menus. + * * @namespace Blockly.WidgetDiv */ import * as goog from '../closure/goog/goog.js'; @@ -39,7 +40,8 @@ let containerDiv: HTMLDivElement|null; /** * Returns the HTML container for editor widgets. - * @return The editor widget container. + * + * @returns The editor widget container. * @alias Blockly.WidgetDiv.getDiv */ export function getDiv(): HTMLDivElement|null { @@ -48,6 +50,7 @@ export function getDiv(): HTMLDivElement|null { /** * Allows unit tests to reset the div. + * * @param newDiv The new value for the DIV field. * @alias Blockly.WidgetDiv.testOnly_setDiv * @ignore @@ -58,6 +61,7 @@ export function testOnly_setDiv(newDiv: HTMLDivElement|null) { /** * Create the widget div and inject it onto the page. + * * @alias Blockly.WidgetDiv.createDom */ export function createDom() { @@ -73,6 +77,7 @@ export function createDom() { /** * Initialize and display the widget div. Close the old one if needed. + * * @param newOwner The object that will be using this container. * @param rtl Right-to-left (true) or left-to-right (false). * @param newDispose Optional cleanup function to be run when the widget is @@ -100,6 +105,7 @@ export function show( /** * Destroy the widget and hide the div. + * * @alias Blockly.WidgetDiv.hide */ export function hide() { @@ -135,7 +141,8 @@ export function hide() { /** * Is the container visible? - * @return True if visible. + * + * @returns True if visible. * @alias Blockly.WidgetDiv.isVisible */ export function isVisible(): boolean { @@ -145,6 +152,7 @@ export function isVisible(): boolean { /** * Destroy the widget and hide the div if it is being used by the specified * object. + * * @param oldOwner The object that was using this container. * @alias Blockly.WidgetDiv.hideIfOwner */ @@ -156,6 +164,7 @@ export function hideIfOwner(oldOwner: AnyDuringMigration) { /** * Set the widget div's position and height. This function does nothing clever: * it will not ensure that your widget div ends up in the visible window. + * * @param x Horizontal location (window coordinates, not body). * @param y Vertical location (window coordinates, not body). * @param height The height of the widget div (pixels). @@ -171,6 +180,7 @@ function positionInternal(x: number, y: number, height: number) { * The widget should be placed adjacent to but not overlapping the anchor * rectangle. The preferred position is directly below and aligned to the left * (LTR) or right (RTL) side of the anchor. + * * @param viewportBBox The bounding rectangle of the current viewport, in window * coordinates. * @param anchorBBox The bounding rectangle of the anchor, in window @@ -197,13 +207,14 @@ export function positionWithAnchor( /** * Calculate an x position (in window coordinates) such that the widget will not * be offscreen on the right or left. + * * @param viewportBBox The bounding rectangle of the current viewport, in window * coordinates. * @param anchorBBox The bounding rectangle of the anchor, in window * coordinates. * @param widgetSize The dimensions of the widget inside the widget div. * @param rtl Whether the Blockly workspace is in RTL mode. - * @return A valid x-coordinate for the top left corner of the widget div, in + * @returns A valid x-coordinate for the top left corner of the widget div, in * window coordinates. */ function calculateX( @@ -228,12 +239,13 @@ function calculateX( /** * Calculate a y position (in window coordinates) such that the widget will not * be offscreen on the top or bottom. + * * @param viewportBBox The bounding rectangle of the current viewport, in window * coordinates. * @param anchorBBox The bounding rectangle of the anchor, in window * coordinates. * @param widgetSize The dimensions of the widget inside the widget div. - * @return A valid y-coordinate for the top left corner of the widget div, in + * @returns A valid y-coordinate for the top left corner of the widget div, in * window coordinates. */ function calculateY( diff --git a/core/workspace.ts b/core/workspace.ts index 9cb3862ee..455e0882e 100644 --- a/core/workspace.ts +++ b/core/workspace.ts @@ -6,6 +6,7 @@ /** * Object representing a workspace. + * * @class */ import * as goog from '../closure/goog/goog.js'; @@ -36,6 +37,7 @@ import type {WorkspaceComment} from './workspace_comment.js'; /** * Class for a workspace. This is a data structure that contains blocks. * There is no UI, and can be created headlessly. + * * @alias Blockly.Workspace */ export class Workspace implements IASTNodeLocation { @@ -59,6 +61,7 @@ export class Workspace implements IASTNodeLocation { /** * Is this workspace the surface for a flyout? + * * @internal */ internalIsFlyout = false; @@ -70,6 +73,7 @@ export class Workspace implements IASTNodeLocation { /** * Is this workspace the surface for a mutator? + * * @internal */ internalIsMutator = false; @@ -82,6 +86,7 @@ export class Workspace implements IASTNodeLocation { /** * Returns `true` if the workspace is currently in the process of a bulk * clear. + * * @internal */ isClearing = false; @@ -143,6 +148,7 @@ export class Workspace implements IASTNodeLocation { /** * Dispose of this workspace. * Unlink from all DOM elements to prevent memory leaks. + * * @suppress {checkTypes} */ dispose() { @@ -155,9 +161,10 @@ export class Workspace implements IASTNodeLocation { /** * Compare function for sorting objects (blocks, comments, etc) by position; * top to bottom (with slight LTR or RTL bias). + * * @param a The first object to compare. * @param b The second object to compare. - * @return The comparison value. This tells Array.sort() how to change object + * @returns The comparison value. This tells Array.sort() how to change object * a's index. */ private sortObjects_(a: Block|WorkspaceComment, b: Block|WorkspaceComment): @@ -182,6 +189,7 @@ export class Workspace implements IASTNodeLocation { /** * Adds a block to the list of top blocks. + * * @param block Block to add. */ addTopBlock(block: Block) { @@ -190,6 +198,7 @@ export class Workspace implements IASTNodeLocation { /** * Removes a block from the list of top blocks. + * * @param block Block to remove. */ removeTopBlock(block: Block) { @@ -201,8 +210,9 @@ export class Workspace implements IASTNodeLocation { /** * Finds the top-level blocks and returns them. Blocks are optionally sorted * by position; top to bottom (with slight LTR or RTL bias). + * * @param ordered Sort the list if true. - * @return The top-level block objects. + * @returns The top-level block objects. */ getTopBlocks(ordered: boolean): Block[] { // Copy the topBlocks_ list. @@ -225,6 +235,7 @@ export class Workspace implements IASTNodeLocation { /** * Add a block to the list of blocks keyed by type. + * * @param block Block to add. */ addTypedBlock(block: Block) { @@ -236,6 +247,7 @@ export class Workspace implements IASTNodeLocation { /** * Remove a block from the list of blocks keyed by type. + * * @param block Block to remove. */ removeTypedBlock(block: Block) { @@ -248,9 +260,10 @@ export class Workspace implements IASTNodeLocation { /** * Finds the blocks with the associated type and returns them. Blocks are * optionally sorted by position; top to bottom (with slight LTR or RTL bias). + * * @param type The type of block to search for. * @param ordered Sort the list if true. - * @return The blocks of the given type. + * @returns The blocks of the given type. */ getBlocksByType(type: string, ordered: boolean): Block[] { if (!this.typedBlocksDB.has(type)) { @@ -278,6 +291,7 @@ export class Workspace implements IASTNodeLocation { /** * Adds a comment to the list of top comments. + * * @param comment comment to add. * @internal */ @@ -296,6 +310,7 @@ export class Workspace implements IASTNodeLocation { /** * Removes a comment from the list of top comments. + * * @param comment comment to remove. * @internal */ @@ -313,8 +328,9 @@ export class Workspace implements IASTNodeLocation { /** * Finds the top-level comments and returns them. Comments are optionally * sorted by position; top to bottom (with slight LTR or RTL bias). + * * @param ordered Sort the list if true. - * @return The top-level comment objects. + * @returns The top-level comment objects. * @internal */ getTopComments(ordered: boolean): WorkspaceComment[] { @@ -339,8 +355,9 @@ export class Workspace implements IASTNodeLocation { /** * Find all blocks in workspace. Blocks are optionally sorted * by position; top to bottom (with slight LTR or RTL bias). + * * @param ordered Sort the list if true. - * @return Array of blocks. + * @returns Array of blocks. */ getAllBlocks(ordered: boolean): Block[] { let blocks: AnyDuringMigration[]; @@ -398,6 +415,7 @@ export class Workspace implements IASTNodeLocation { /** * Rename a variable by updating its name in the variable map. Identify the * variable to rename with the given ID. + * * @param id ID of the variable to rename. * @param newName New variable name. */ @@ -407,13 +425,14 @@ export class Workspace implements IASTNodeLocation { /** * Create a variable with a given name, optional type, and optional ID. + * * @param name The name of the variable. This must be unique across variables * and procedures. * @param opt_type The type of the variable like 'int' or 'string'. * Does not need to be unique. Field_variable can filter variables based * on their type. This will default to '' which is a specific type. * @param opt_id The unique ID of the variable. This will default to a UUID. - * @return The newly created variable. + * @returns The newly created variable. */ createVariable(name: string, opt_type?: string|null, opt_id?: string|null): VariableModel { @@ -422,8 +441,9 @@ export class Workspace implements IASTNodeLocation { /** * Find all the uses of the given variable, which is identified by ID. + * * @param id ID of the variable to find. - * @return Array of block usages. + * @returns Array of block usages. */ getVariableUsesById(id: string): Block[] { return this.variableMap_.getVariableUsesById(id); @@ -432,6 +452,7 @@ export class Workspace implements IASTNodeLocation { /** * Delete a variables by the passed in ID and all of its uses from this * workspace. May prompt the user for confirmation. + * * @param id ID of variable to delete. */ deleteVariableById(id: string) { @@ -441,10 +462,11 @@ export class Workspace implements IASTNodeLocation { /** * Find the variable by the given name and return it. Return null if not * found. + * * @param name The name to check for. * @param opt_type The type of the variable. If not provided it defaults to * the empty string, which is a specific type. - * @return The variable with the given name. + * @returns The variable with the given name. */ getVariable(name: string, opt_type?: string): VariableModel|null { // TODO (#1559): Possibly delete this function after resolving #1559. @@ -453,8 +475,9 @@ export class Workspace implements IASTNodeLocation { /** * Find the variable by the given ID and return it. Return null if not found. + * * @param id The ID to check for. - * @return The variable with the given ID. + * @returns The variable with the given ID. */ getVariableById(id: string): VariableModel|null { return this.variableMap_.getVariableById(id); @@ -463,8 +486,9 @@ export class Workspace implements IASTNodeLocation { /** * Find the variable with the specified type. If type is null, return list of * variables with empty string type. + * * @param type Type of the variables to find. - * @return The sought after variables of the passed in type. An empty array if + * @returns The sought after variables of the passed in type. An empty array if * none are found. */ getVariablesOfType(type: string|null): VariableModel[] { @@ -473,7 +497,8 @@ export class Workspace implements IASTNodeLocation { /** * Return all variable types. - * @return List of variable types. + * + * @returns List of variable types. * @internal */ getVariableTypes(): string[] { @@ -482,7 +507,8 @@ export class Workspace implements IASTNodeLocation { /** * Return all variables of all types. - * @return List of variable models. + * + * @returns List of variable models. */ getAllVariables(): VariableModel[] { return this.variableMap_.getAllVariables(); @@ -490,7 +516,8 @@ export class Workspace implements IASTNodeLocation { /** * Returns all variable names of all types. - * @return List of all variable names of all types. + * + * @returns List of all variable names of all types. */ getAllVariableNames(): string[] { return this.variableMap_.getAllVariableNames(); @@ -500,7 +527,8 @@ export class Workspace implements IASTNodeLocation { * Returns the horizontal offset of the workspace. * Intended for LTR/RTL compatibility in XML. * Not relevant for a headless workspace. - * @return Width. + * + * @returns Width. */ getWidth(): number { return 0; @@ -508,11 +536,12 @@ export class Workspace implements IASTNodeLocation { /** * Obtain a newly created block. + * * @param prototypeName Name of the language object containing type-specific * functions for this block. * @param opt_id Optional ID. Use this ID if provided, otherwise create a new * ID. - * @return The created block. + * @returns The created block. */ // eslint-disable-next-line @typescript-eslint/no-unused-vars newBlock(prototypeName: string, opt_id?: string): Block { @@ -524,7 +553,8 @@ export class Workspace implements IASTNodeLocation { /** * The number of blocks that may be added to the workspace before reaching * the maxBlocks. - * @return Number of blocks left. + * + * @returns Number of blocks left. */ remainingCapacity(): number { if (isNaN(this.options.maxBlocks)) { @@ -537,8 +567,9 @@ export class Workspace implements IASTNodeLocation { /** * The number of blocks of the given type that may be added to the workspace * before reaching the maxInstances allowed for that type. + * * @param type Type of block to return capacity for. - * @return Number of blocks of type left. + * @returns Number of blocks of type left. */ remainingCapacityOfType(type: string): number { if (!this.options.maxInstances) { @@ -557,9 +588,10 @@ export class Workspace implements IASTNodeLocation { * created. If the total number of blocks represented by the map is more * than the total remaining capacity, it returns false. If a type count is * more than the remaining capacity for that type, it returns false. + * * @param typeCountsMap A map of types to counts (usually representing blocks * to be created). - * @return True if there is capacity for the given map, false otherwise. + * @returns True if there is capacity for the given map, false otherwise. */ isCapacityAvailable(typeCountsMap: AnyDuringMigration): boolean { if (!this.hasBlockLimits()) { @@ -581,7 +613,8 @@ export class Workspace implements IASTNodeLocation { /** * Checks if the workspace has any limits on the maximum number of blocks, * or the maximum number of blocks of specific types. - * @return True if it has block limits, false otherwise. + * + * @returns True if it has block limits, false otherwise. */ hasBlockLimits(): boolean { return this.options.maxBlocks !== Infinity || !!this.options.maxInstances; @@ -589,7 +622,8 @@ export class Workspace implements IASTNodeLocation { /** * Gets the undo stack for workplace. - * @return undo stack + * + * @returns undo stack * @internal */ getUndoStack(): Abstract[] { @@ -598,7 +632,8 @@ export class Workspace implements IASTNodeLocation { /** * Gets the redo stack for workplace. - * @return redo stack + * + * @returns redo stack * @internal */ getRedoStack(): Abstract[] { @@ -607,6 +642,7 @@ export class Workspace implements IASTNodeLocation { /** * Undo or redo the previous action. + * * @param redo False if undo, true if redo. */ undo(redo: boolean) { @@ -654,8 +690,9 @@ export class Workspace implements IASTNodeLocation { * Note that there may be a few recent events already on the stack. Thus the * new change listener might be called with events that occurred a few * milliseconds before the change listener was added. + * * @param func Function to call. - * @return Obsolete return value, ignore. + * @returns Obsolete return value, ignore. */ addChangeListener(func: Function): Function { this.listeners_.push(func); @@ -664,6 +701,7 @@ export class Workspace implements IASTNodeLocation { /** * Stop listening for this workspace's changes. + * * @param func Function to stop calling. */ removeChangeListener(func: Function) { @@ -672,6 +710,7 @@ export class Workspace implements IASTNodeLocation { /** * Fire a change event. + * * @param event Event to fire. */ fireChangeListener(event: Abstract) { @@ -690,8 +729,9 @@ export class Workspace implements IASTNodeLocation { /** * Find the block on this workspace with the specified ID. + * * @param id ID of block to find. - * @return The sought after block, or null if not found. + * @returns The sought after block, or null if not found. */ getBlockById(id: string): Block|null { return this.blockDB.get(id) || null; @@ -699,6 +739,7 @@ export class Workspace implements IASTNodeLocation { /** * Set a block on this workspace with the specified ID. + * * @param id ID of block to set. * @param block The block to set. * @internal @@ -709,6 +750,7 @@ export class Workspace implements IASTNodeLocation { /** * Delete a block off this workspace with the specified ID. + * * @param id ID of block to delete. * @internal */ @@ -718,8 +760,9 @@ export class Workspace implements IASTNodeLocation { /** * Find the comment on this workspace with the specified ID. + * * @param id ID of comment to find. - * @return The sought after comment, or null if not found. + * @returns The sought after comment, or null if not found. * @internal */ getCommentById(id: string): WorkspaceComment|null { @@ -729,9 +772,10 @@ export class Workspace implements IASTNodeLocation { /** * Checks whether all value and statement inputs in the workspace are filled * with blocks. + * * @param opt_shadowBlocksAreFilled An optional argument controlling whether * shadow blocks are counted as filled. Defaults to true. - * @return True if all inputs are filled, false otherwise. + * @returns True if all inputs are filled, false otherwise. */ allInputsFilled(opt_shadowBlocksAreFilled?: boolean): boolean { const blocks = this.getTopBlocks(false); @@ -747,7 +791,8 @@ export class Workspace implements IASTNodeLocation { /** * Return the variable map that contains "potential" variables. * These exist in the flyout but not in the workspace. - * @return The potential variable map. + * + * @returns The potential variable map. * @internal */ getPotentialVariableMap(): VariableMap|null { @@ -756,6 +801,7 @@ export class Workspace implements IASTNodeLocation { /** * Create and store the potential variable map for this workspace. + * * @internal */ createPotentialVariableMap() { @@ -764,7 +810,8 @@ export class Workspace implements IASTNodeLocation { /** * Return the map of all variables on the workspace. - * @return The variable map. + * + * @returns The variable map. */ getVariableMap(): VariableMap { return this.variableMap_; @@ -772,6 +819,7 @@ export class Workspace implements IASTNodeLocation { /** * Set the map of all variables on the workspace. + * * @param variableMap The variable map. * @internal */ @@ -781,8 +829,9 @@ export class Workspace implements IASTNodeLocation { /** * Find the workspace with the specified ID. + * * @param id ID of workspace to find. - * @return The sought after workspace or null if not found. + * @returns The sought after workspace or null if not found. */ static getById(id: string): Workspace|null { return common.getWorkspaceById(id); @@ -790,7 +839,8 @@ export class Workspace implements IASTNodeLocation { /** * Find all workspaces. - * @return Array of workspaces. + * + * @returns Array of workspaces. */ static getAll(): Workspace[] { return common.getAllWorkspaces(); diff --git a/core/workspace_comment_svg.ts b/core/workspace_comment_svg.ts index a71af912b..486dce8b7 100644 --- a/core/workspace_comment_svg.ts +++ b/core/workspace_comment_svg.ts @@ -6,6 +6,7 @@ /** * Object representing a code comment on a rendered workspace. + * * @class */ import * as goog from '../closure/goog/goog.js'; @@ -49,6 +50,7 @@ const TEXTAREA_OFFSET = 2; /** * Class for a workspace comment's SVG representation. + * * @alias Blockly.WorkspaceCommentSvg */ export class WorkspaceCommentSvg extends WorkspaceComment implements @@ -56,6 +58,7 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements /** * The width and height to use to size a workspace comment when it is first * added, before it has been edited by the user. + * * @internal */ static DEFAULT_SIZE = 100; @@ -133,6 +136,7 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements /** * Dispose of this comment. + * * @internal */ override dispose() { @@ -191,6 +195,7 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements /** * Handle a mouse-down on an SVG comment. + * * @param e Mouse down event or touch start event. */ private pathMouseDown_(e: Event) { @@ -202,6 +207,7 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements /** * Show the context menu for this workspace comment. + * * @param e Mouse event. * @internal */ @@ -214,6 +220,7 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements /** * Select this comment. Highlight it visually. + * * @internal */ select() { @@ -240,6 +247,7 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements /** * Unselect this comment. Remove its highlighting. + * * @internal */ unselect() { @@ -256,6 +264,7 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements /** * Select this comment. Highlight it visually. + * * @internal */ addSelect() { @@ -265,6 +274,7 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements /** * Unselect this comment. Remove its highlighting. + * * @internal */ removeSelect() { @@ -274,6 +284,7 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements /** * Focus this comment. Highlight it visually. + * * @internal */ addFocus() { @@ -282,6 +293,7 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements /** * Unfocus this comment. Remove its highlighting. + * * @internal */ removeFocus() { @@ -294,7 +306,8 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements * If the comment is on the workspace, (0, 0) is the origin of the workspace * coordinate system. * This does not change with workspace scale. - * @return Object with .x and .y properties in workspace coordinates. + * + * @returns Object with .x and .y properties in workspace coordinates. * @internal */ getRelativeToSurfaceXY(): Coordinate { @@ -334,6 +347,7 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements /** * Move a comment by a relative offset. + * * @param dx Horizontal offset, in workspace units. * @param dy Vertical offset, in workspace units. * @internal @@ -353,6 +367,7 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements /** * Transforms a comment by setting the translation on the transform attribute * of the block's SVG. + * * @param x The x coordinate of the translation in workspace units. * @param y The y coordinate of the translation in workspace units. * @internal @@ -367,6 +382,7 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements * Move this comment to its workspace's drag surface, accounting for * positioning. Generally should be called at the same time as * setDragging(true). Does nothing if useDragSurface_ is false. + * * @internal */ moveToDragSurface() { @@ -387,6 +403,7 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements /** * Move this comment during a drag, taking into account whether we are using a * drag surface to translate blocks. + * * @param dragSurface The surface that carries rendered items during a drag, * or null if no drag surface is in use. * @param newLoc The location to translate to, in workspace coordinates. @@ -408,6 +425,7 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements /** * Move the bubble group to the specified location in workspace coordinates. + * * @param x The x position to move to. * @param y The y position to move to. * @internal @@ -428,7 +446,8 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements * Returns the coordinates of a bounding box describing the dimensions of this * comment. * Coordinate system: workspace coordinates. - * @return Object with coordinates of the bounding box. + * + * @returns Object with coordinates of the bounding box. * @internal */ getBoundingRectangle(): Rect { @@ -454,6 +473,7 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements /** * Add or remove the UI indicating if this comment is movable or not. + * * @internal */ updateMovable() { @@ -466,6 +486,7 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements /** * Set whether this comment is movable or not. + * * @param movable True if movable. * @internal */ @@ -476,6 +497,7 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements /** * Set whether this comment is editable or not. + * * @param editable True if editable. */ override setEditable(editable: boolean) { @@ -488,6 +510,7 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements /** * Recursively adds or removes the dragging class to this node and its * children. + * * @param adding True if adding, false if removing. * @internal */ @@ -504,7 +527,8 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements /** * Return the root node of the SVG or null if none exists. - * @return The root SVG node (probably a group). + * + * @returns The root SVG node (probably a group). * @internal */ getSvgRoot(): SVGElement { @@ -513,7 +537,8 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements /** * Returns this comment's text. - * @return Comment text. + * + * @returns Comment text. * @internal */ override getContent(): string { @@ -522,6 +547,7 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements /** * Set this comment's content. + * * @param content Comment content. * @internal */ @@ -534,6 +560,7 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements /** * Update the cursor over this comment by adding or removing a class. + * * @param enable True if the delete cursor should be shown, false otherwise. * @internal */ @@ -549,6 +576,7 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements * Set whether auto-layout of this bubble is enabled. The first time a bubble * is shown it positions itself to not cover any blocks. Once a user has * dragged it to reposition, it renders where the user put it. + * * @param _enable True if auto-layout should be enabled, false otherwise. * @internal */ @@ -557,8 +585,9 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements /** * Encode a comment subtree as XML with XY coordinates. + * * @param opt_noId True if the encoder should skip the comment ID. - * @return Tree of XML elements. + * @returns Tree of XML elements. * @internal */ override toXmlWithXY(opt_noId?: boolean): Element { @@ -589,7 +618,8 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements /** * Encode a comment for copying. - * @return Copy metadata. + * + * @returns Copy metadata. * @internal */ toCopyData(): CopyData { @@ -602,7 +632,8 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements /** * Returns a bounding box describing the dimensions of this comment. - * @return Object with height and width properties in workspace units. + * + * @returns Object with height and width properties in workspace units. * @internal */ getHeightWidth(): {height: number, width: number} { @@ -611,6 +642,7 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements /** * Renders the workspace comment. + * * @internal */ render() { @@ -676,7 +708,8 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements /** * Create the text area for the comment. - * @return The top-level node of the editor. + * + * @returns The top-level node of the editor. */ private createEditor_(): Element { /* Create the editor. Here's the markup that will be generated: @@ -793,6 +826,7 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements /** * Handle a mouse-down on comment's resize corner. + * * @param e Mouse down event. */ private resizeMouseDown_(e: MouseEvent) { @@ -819,6 +853,7 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements /** * Handle a mouse-down on comment's delete icon. + * * @param e Mouse down event. */ private deleteMouseDown_(e: Event) { @@ -831,6 +866,7 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements /** * Handle a mouse-out on comment's delete icon. + * * @param _e Mouse out event. */ private deleteMouseOut_(_e: Event) { @@ -841,6 +877,7 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements /** * Handle a mouse-up on comment's delete icon. + * * @param e Mouse up event. */ private deleteMouseUp_(e: Event) { @@ -864,6 +901,7 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements /** * Handle a mouse-up event while dragging a comment's border or resize handle. + * * @param _e Mouse up event. */ private resizeMouseUp_(_e: Event) { @@ -873,6 +911,7 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements /** * Resize this comment to follow the mouse. + * * @param e Mouse move event. */ private resizeMouseMove_(e: MouseEvent) { @@ -905,6 +944,7 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements /** * Set size + * * @param width width of the container * @param height height of the container */ @@ -971,6 +1011,7 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements /** * Set the focus on the text area. + * * @internal */ setFocus() { @@ -994,6 +1035,7 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements /** * Remove focus from the text area. + * * @internal */ blurFocus() { @@ -1018,11 +1060,12 @@ export class WorkspaceCommentSvg extends WorkspaceComment implements /** * Decode an XML comment tag and create a rendered comment on the workspace. + * * @param xmlComment XML comment element. * @param workspace The workspace. * @param opt_wsWidth The width of the workspace, which is used to position * comments correctly in RTL. - * @return The created workspace comment. + * @returns The created workspace comment. * @internal */ static fromXmlRendered( diff --git a/core/workspace_drag_surface_svg.ts b/core/workspace_drag_surface_svg.ts index fe2e8cfd9..b9320b347 100644 --- a/core/workspace_drag_surface_svg.ts +++ b/core/workspace_drag_surface_svg.ts @@ -9,6 +9,7 @@ * Blocks are moved into this SVG during a drag, improving performance. * The entire SVG is translated using CSS translation instead of SVG so the * blocks are never repainted during drag improving performance. + * * @class */ import * as goog from '../closure/goog/goog.js'; @@ -24,6 +25,7 @@ import * as svgMath from './utils/svg_math.js'; * Blocks are moved into this SVG during a drag, improving performance. * The entire SVG is translated using CSS transforms instead of SVG so the * blocks are never repainted during drag improving performance. + * * @alias Blockly.WorkspaceDragSurfaceSvg */ export class WorkspaceDragSurfaceSvg { @@ -75,6 +77,7 @@ export class WorkspaceDragSurfaceSvg { * We translate the drag surface instead of the blocks inside the surface * so that the browser avoids repainting the SVG. * Because of this, the drag coordinates must be adjusted by scale. + * * @param x X translation for the entire surface * @param y Y translation for the entire surface * @internal @@ -92,7 +95,8 @@ export class WorkspaceDragSurfaceSvg { /** * Reports the surface translation in scaled workspace coordinates. * Use this when finishing a drag to return blocks to the correct position. - * @return Current translation of the surface + * + * @returns Current translation of the surface * @internal */ getSurfaceTranslation(): Coordinate { @@ -102,6 +106,7 @@ export class WorkspaceDragSurfaceSvg { /** * Move the blockCanvas and bubbleCanvas out of the surface SVG and on to * newSurface. + * * @param newSurface The element to put the drag surface contents into. * @internal */ @@ -141,20 +146,21 @@ export class WorkspaceDragSurfaceSvg { } /** - * Set the SVG to have the block canvas and bubble canvas in it and then - * show the surface. - * @param blockCanvas The block canvas element from the - * workspace. - * @param bubbleCanvas The element that contains the + * Set the SVG to have the block canvas and bubble canvas in it and then + * show the surface. + * + * @param blockCanvas The block canvas element from the + * workspace. + * @param bubbleCanvas The element that contains the bubbles. - * @param previousSibling The element to insert the block canvas and + * @param previousSibling The element to insert the block canvas and bubble canvas after when it goes back in the DOM at the end of a drag. - * @param width The width of the workspace SVG element. - * @param height The height of the workspace SVG element. - * @param scale The scale of the workspace being dragged. - * @internal - */ + * @param width The width of the workspace SVG element. + * @param height The height of the workspace SVG element. + * @param scale The scale of the workspace being dragged. + * @internal + */ setContentsAndShow( blockCanvas: SVGElement, bubbleCanvas: SVGElement, previousSibling: Element, width: number, height: number, scale: number) { diff --git a/core/workspace_dragger.ts b/core/workspace_dragger.ts index 0fc016f10..686807e39 100644 --- a/core/workspace_dragger.ts +++ b/core/workspace_dragger.ts @@ -6,6 +6,7 @@ /** * Methods for dragging a workspace visually. + * * @class */ import * as goog from '../closure/goog/goog.js'; @@ -22,6 +23,7 @@ import type {WorkspaceSvg} from './workspace_svg.js'; * Note that the workspace itself manages whether or not it has a drag surface * and how to do translations based on that. This simply passes the right * commands based on events. + * * @alias Blockly.WorkspaceDragger */ export class WorkspaceDragger { @@ -46,6 +48,7 @@ export class WorkspaceDragger { /** * Sever all links from this object. + * * @suppress {checkTypes} * @internal */ @@ -57,6 +60,7 @@ export class WorkspaceDragger { /** * Start dragging the workspace. + * * @internal */ startDrag() { @@ -68,6 +72,7 @@ export class WorkspaceDragger { /** * Finish dragging the workspace and put everything back where it belongs. + * * @param currentDragDeltaXY How far the pointer has moved from the position * at the start of the drag, in pixel coordinates. * @internal @@ -80,6 +85,7 @@ export class WorkspaceDragger { /** * Move the workspace based on the most recent mouse movements. + * * @param currentDragDeltaXY How far the pointer has moved from the position * at the start of the drag, in pixel coordinates. * @internal diff --git a/core/xml.ts b/core/xml.ts index 3daf990d1..7071eacc2 100644 --- a/core/xml.ts +++ b/core/xml.ts @@ -6,6 +6,7 @@ /** * XML reader and writer. + * * @namespace Blockly.Xml */ import * as goog from '../closure/goog/goog.js'; @@ -39,9 +40,10 @@ import type {WorkspaceSvg} from './workspace_svg.js'; /** * Encode a block tree as XML. + * * @param workspace The workspace containing blocks. * @param opt_noId True if the encoder should skip the block IDs. - * @return XML DOM element. + * @returns XML DOM element. * @alias Blockly.Xml.workspaceToDom */ export function workspaceToDom( @@ -67,8 +69,9 @@ export function workspaceToDom( /** * Encode a list of variables as XML. + * * @param variableList List of all variable models. - * @return Tree of XML elements. + * @returns Tree of XML elements. * @alias Blockly.Xml.variablesToDom */ export function variablesToDom(variableList: VariableModel[]): Element { @@ -88,9 +91,10 @@ export function variablesToDom(variableList: VariableModel[]): Element { /** * Encode a block subtree as XML with XY coordinates. + * * @param block The root block to encode. * @param opt_noId True if the encoder should skip the block ID. - * @return Tree of XML elements or an empty document fragment if the block was + * @returns Tree of XML elements or an empty document fragment if the block was * an insertion marker. * @alias Blockly.Xml.blockToDomWithXY */ @@ -123,8 +127,9 @@ export function blockToDomWithXY(block: Block, opt_noId?: boolean): Element| /** * Encode a field as XML. + * * @param field The field to encode. - * @return XML element, or null if the field did not need to be serialized. + * @returns XML element, or null if the field did not need to be serialized. */ function fieldToDom(field: Field): Element|null { if (field.isSerializable()) { @@ -138,6 +143,7 @@ function fieldToDom(field: Field): Element|null { /** * Encode all of a block's fields as XML and attach them to the given tree of * XML elements. + * * @param block A block with fields to be encoded. * @param element The XML element to which the field DOM should be attached. */ @@ -156,9 +162,10 @@ function allFieldsToDom(block: Block, element: Element) { /** * Encode a block subtree as XML. + * * @param block The root block to encode. * @param opt_noId True if the encoder should skip the block ID. - * @return Tree of XML elements or an empty document fragment if the block was + * @returns Tree of XML elements or an empty document fragment if the block was * an insertion marker. * @alias Blockly.Xml.blockToDom */ @@ -289,9 +296,10 @@ export function blockToDom(block: Block, opt_noId?: boolean): Element| /** * Deeply clone the shadow's DOM so that changes don't back-wash to the block. + * * @param shadow A tree of XML elements. * @param opt_noId True if the encoder should skip the block ID. - * @return A tree of XML elements. + * @returns A tree of XML elements. */ function cloneShadow(shadow: Element, opt_noId?: boolean): Element { shadow = shadow.cloneNode(true) as Element; @@ -335,8 +343,9 @@ function cloneShadow(shadow: Element, opt_noId?: boolean): Element { * Converts a DOM structure into plain text. * Currently the text format is fairly ugly: all one line with no whitespace, * unless the DOM itself has whitespace built-in. + * * @param dom A tree of XML nodes. - * @return Text representation. + * @returns Text representation. * @alias Blockly.Xml.domToText */ export function domToText(dom: Node): string { @@ -348,8 +357,9 @@ export function domToText(dom: Node): string { /** * Converts a DOM structure into properly indented text. + * * @param dom A tree of XML elements. - * @return Text representation. + * @returns Text representation. * @alias Blockly.Xml.domToPrettyText */ export function domToPrettyText(dom: Node): string { @@ -380,8 +390,9 @@ export function domToPrettyText(dom: Node): string { /** * Converts an XML string into a DOM structure. + * * @param text An XML string. - * @return A DOM object representing the singular child of the document element. + * @returns A DOM object representing the singular child of the document element. * @throws if the text doesn't parse. * @alias Blockly.Xml.textToDom */ @@ -397,9 +408,10 @@ export function textToDom(text: string): Element { /** * Clear the given workspace then decode an XML DOM and * create blocks on the workspace. + * * @param xml XML DOM. * @param workspace The workspace. - * @return An array containing new block IDs. + * @returns An array containing new block IDs. * @alias Blockly.Xml.clearWorkspaceAndLoadFromXml */ export function clearWorkspaceAndLoadFromXml( @@ -415,9 +427,10 @@ export function clearWorkspaceAndLoadFromXml( /** * Decode an XML DOM and create blocks on the workspace. + * * @param xml XML DOM. * @param workspace The workspace. - * @return An array containing new block IDs. + * @returns An array containing new block IDs. * @suppress {strictModuleDepCheck} Suppress module check while workspace * comments are not bundled in. * @alias Blockly.Xml.domToWorkspace @@ -506,9 +519,10 @@ export function domToWorkspace(xml: Element, workspace: Workspace): string[] { /** * Decode an XML DOM and create blocks on the workspace. Position the new * blocks immediately below prior blocks, aligned by their starting edge. + * * @param xml The XML DOM. * @param workspace The workspace to add to. - * @return An array containing new block IDs. + * @returns An array containing new block IDs. * @alias Blockly.Xml.appendDomToWorkspace */ export function appendDomToWorkspace( @@ -559,9 +573,10 @@ export function appendDomToWorkspace( /** * Decode an XML block tag and create a block (and possibly sub blocks) on the * workspace. + * * @param xmlBlock XML block element. * @param workspace The workspace. - * @return The root block created. + * @returns The root block created. * @alias Blockly.Xml.domToBlock */ export function domToBlock(xmlBlock: Element, workspace: Workspace): Block { @@ -623,6 +638,7 @@ export function domToBlock(xmlBlock: Element, workspace: Workspace): Block { /** * Decode an XML list of variables and add the variables to the workspace. + * * @param xmlVariables List of XML variable elements. * @param workspace The workspace to which the variable should be added. * @alias Blockly.Xml.domToVariables @@ -653,8 +669,9 @@ interface childNodeTagMap { /** * Creates a mapping of childNodes for each supported XML tag for the provided * xmlBlock. Logs a warning for any encountered unsupported tags. + * * @param xmlBlock XML block element. - * @return The childNode map from nodeName to node. + * @returns The childNode map from nodeName to node. */ function mapSupportedXmlTags(xmlBlock: Element): childNodeTagMap { const childNodeMap = { @@ -704,9 +721,10 @@ function mapSupportedXmlTags(xmlBlock: Element): childNodeTagMap { /** * Applies mutation tag child nodes to the given block. + * * @param xmlChildren Child nodes. * @param block The block to apply the child nodes on. - * @return True if mutation may have added some elements that need + * @returns True if mutation may have added some elements that need * initialization (requiring initSvg call). */ function applyMutationTagNodes(xmlChildren: Element[], block: Block): boolean { @@ -727,6 +745,7 @@ function applyMutationTagNodes(xmlChildren: Element[], block: Block): boolean { /** * Applies comment tag child nodes to the given block. + * * @param xmlChildren Child nodes. * @param block The block to apply the child nodes on. */ @@ -761,6 +780,7 @@ function applyCommentTagNodes(xmlChildren: Element[], block: Block) { /** * Applies data tag child nodes to the given block. + * * @param xmlChildren Child nodes. * @param block The block to apply the child nodes on. */ @@ -773,6 +793,7 @@ function applyDataTagNodes(xmlChildren: Element[], block: Block) { /** * Applies field tag child nodes to the given block. + * * @param xmlChildren Child nodes. * @param block The block to apply the child nodes on. */ @@ -788,8 +809,9 @@ function applyFieldTagNodes(xmlChildren: Element[], block: Block) { /** * Finds any enclosed blocks or shadows within this XML node. + * * @param xmlNode The XML node to extract child block info from. - * @return Any found child block. + * @returns Any found child block. */ function findChildBlocks(xmlNode: Element): {childBlockElement: Element|null, childShadowElement: Element|null} { @@ -814,6 +836,7 @@ function findChildBlocks(xmlNode: Element): } /** * Applies input child nodes (value or statement) to the given block. + * * @param xmlChildren Child nodes. * @param workspace The workspace containing the given block. * @param block The block to apply the child nodes on. @@ -851,6 +874,7 @@ function applyInputTagNodes( /** * Applies next child nodes to the given block. + * * @param xmlChildren Child nodes. * @param workspace The workspace containing the given block. * @param block The block to apply the child nodes on. @@ -883,13 +907,14 @@ function applyNextTagNodes( /** * Decode an XML block tag and create a block (and possibly sub blocks) on the * workspace. + * * @param xmlBlock XML block element. * @param workspace The workspace. * @param parentConnection The parent connection to to connect this block to * after instantiating. * @param connectedToParentNext Whether the provided parent connection is a next * connection, rather than output or statement. - * @return The root block created. + * @returns The root block created. */ function domToBlockHeadless( xmlBlock: Element, workspace: Workspace, parentConnection?: Connection, @@ -988,6 +1013,7 @@ function domToBlockHeadless( /** * Decode an XML field tag and set the value of that field on the given block. + * * @param block The block that is currently being deserialized. * @param fieldName The name of the field on the block. * @param xml The field tag to decode. @@ -1004,6 +1030,7 @@ function domToField(block: Block, fieldName: string, xml: Element) { /** * Remove any 'next' block (statements in a stack). + * * @param xmlBlock XML block element or an empty DocumentFragment if the block * was an insertion marker. * @alias Blockly.Xml.deleteNext diff --git a/core/zoom_controls.ts b/core/zoom_controls.ts index 3b681f87a..73f7546b9 100644 --- a/core/zoom_controls.ts +++ b/core/zoom_controls.ts @@ -6,6 +6,7 @@ /** * Object representing a zoom icons. + * * @class */ import * as goog from '../closure/goog/goog.js'; @@ -35,6 +36,7 @@ import type {WorkspaceSvg} from './workspace_svg.js'; /** * Class for a zoom controls. + * * @alias Blockly.ZoomControls */ export class ZoomControls implements IPositionable { @@ -116,7 +118,8 @@ export class ZoomControls implements IPositionable { /** * Create the zoom controls. - * @return The zoom controls SVG group. + * + * @returns The zoom controls SVG group. */ createDom(): SVGElement { this.svgGroup_ = dom.createSvgElement(Svg.G, {}); @@ -168,7 +171,8 @@ export class ZoomControls implements IPositionable { /** * Returns the bounding rectangle of the UI element in pixel units relative to * the Blockly injection div. - * @return The UI elements's bounding box. Null if bounding box should be + * + * @returns The UI elements's bounding box. Null if bounding box should be * ignored by other UI elements. */ getBoundingRectangle(): Rect|null { @@ -185,6 +189,7 @@ export class ZoomControls implements IPositionable { * Positions the zoom controls. * It is positioned in the opposite corner to the corner the * categories/toolbox starts at. + * * @param metrics The workspace metrics. * @param savedPositions List of rectangles that are already on the workspace. */ @@ -240,6 +245,7 @@ export class ZoomControls implements IPositionable { /** * Create the zoom in icon and its event handler. + * * @param rnd The random string to use as a suffix in the clip path's ID. * These IDs must be unique in case there are multiple Blockly instances * on the same page. @@ -286,6 +292,7 @@ export class ZoomControls implements IPositionable { /** * Create the zoom out icon and its event handler. + * * @param rnd The random string to use as a suffix in the clip path's ID. * These IDs must be unique in case there are multiple Blockly instances * on the same page. @@ -332,6 +339,7 @@ export class ZoomControls implements IPositionable { /** * Handles a mouse down event on the zoom in or zoom out buttons on the * workspace. + * * @param amount Amount of zooming. Negative amount values zoom out, and * positive amount values zoom in. * @param e A mouse down event. @@ -347,6 +355,7 @@ export class ZoomControls implements IPositionable { /** * Create the zoom reset icon and its event handler. + * * @param rnd The random string to use as a suffix in the clip path's ID. * These IDs must be unique in case there are multiple Blockly instances * on the same page. @@ -387,6 +396,7 @@ export class ZoomControls implements IPositionable { /** * Handles a mouse down event on the reset zoom button on the workspace. + * * @param e A mouse down event. */ private resetZoom_(e: Event) {