From d8fbe1b05bbada5faf56ac2cb533f480d88d8fc4 Mon Sep 17 00:00:00 2001 From: Monica Kozbial <6621618+moniika@users.noreply.github.com> Date: Mon, 27 Sep 2021 14:42:54 -0700 Subject: [PATCH] Add namespace and alias annotations to jsdoc (#5550) * Add annotations to files under core/events * Add annotations to files under core/interfaces * Add annotations to files under core/keyboard_nav * Add annotations to files under core/renderers * Add annotations to files under core/serialization * Add annotations to files under core/theme * Add annotations to files under core/toolbox * Add annotations to files under core/utils * Add annotations to files under core --- core/block.js | 5 ++ core/block_animations.js | 8 ++ core/block_drag_surface.js | 10 +++ core/block_dragger.js | 5 ++ core/block_svg.js | 5 ++ core/blockly.js | 2 +- core/blockly_options.js | 5 ++ core/blocks.js | 3 +- core/browser_events.js | 12 +++ core/bubble.js | 5 ++ core/bubble_dragger.js | 5 ++ core/bump_objects.js | 7 ++ core/clipboard.js | 7 ++ core/comment.js | 5 ++ core/common.js | 12 +++ core/component_manager.js | 5 ++ core/connection.js | 5 ++ core/connection_checker.js | 6 ++ core/connection_db.js | 7 ++ core/connection_type.js | 5 ++ core/constants.js | 7 ++ core/contextmenu.js | 13 +++ core/contextmenu_items.js | 70 ++++++++++++--- core/contextmenu_registry.js | 5 +- core/css.js | 4 +- core/delete_area.js | 6 ++ core/dialog.js | 10 +++ core/drag_target.js | 6 ++ core/dropdowndiv.js | 5 ++ core/events/events_abstract.js | 8 +- core/events/events_block_base.js | 5 ++ core/events/events_block_change.js | 5 ++ core/events/events_block_create.js | 5 ++ core/events/events_block_delete.js | 5 ++ core/events/events_block_drag.js | 5 ++ core/events/events_block_move.js | 5 ++ core/events/events_bubble_open.js | 5 ++ core/events/events_click.js | 5 ++ core/events/events_comment_base.js | 5 ++ core/events/events_comment_change.js | 5 ++ core/events/events_comment_create.js | 5 ++ core/events/events_comment_delete.js | 5 ++ core/events/events_comment_move.js | 5 ++ core/events/events_marker_move.js | 5 ++ core/events/events_selected.js | 5 ++ core/events/events_theme_change.js | 5 ++ core/events/events_toolbox_item_select.js | 5 ++ core/events/events_trashcan_open.js | 5 ++ core/events/events_ui.js | 6 ++ core/events/events_ui_base.js | 6 ++ core/events/events_var_base.js | 5 ++ core/events/events_var_create.js | 5 ++ core/events/events_var_delete.js | 5 ++ core/events/events_var_rename.js | 5 ++ core/events/events_viewport.js | 5 ++ core/events/utils.js | 89 ++++++++++--------- core/events/workspace_events.js | 5 ++ core/extensions.js | 7 +- core/field.js | 7 ++ core/field_angle.js | 5 ++ core/field_checkbox.js | 5 ++ core/field_colour.js | 5 ++ core/field_dropdown.js | 7 ++ core/field_image.js | 5 ++ core/field_label.js | 6 ++ core/field_label_serializable.js | 7 ++ core/field_multilineinput.js | 5 ++ core/field_number.js | 5 ++ core/field_registry.js | 9 ++ core/field_textinput.js | 5 ++ core/field_variable.js | 5 ++ core/flyout_base.js | 5 ++ core/flyout_button.js | 5 ++ core/flyout_horizontal.js | 5 ++ core/flyout_metrics_manager.js | 5 ++ core/flyout_vertical.js | 5 ++ core/generator.js | 6 ++ core/gesture.js | 6 ++ core/grid.js | 6 ++ core/icon.js | 5 ++ core/inject.js | 5 ++ core/input.js | 5 ++ core/input_types.js | 5 ++ core/insertion_marker_manager.js | 5 ++ core/interfaces/i_ast_node_location.js | 5 ++ core/interfaces/i_ast_node_location_svg.js | 5 ++ .../i_ast_node_location_with_block.js | 6 ++ core/interfaces/i_autohideable.js | 6 ++ core/interfaces/i_block_dragger.js | 5 ++ core/interfaces/i_bounded_element.js | 5 ++ core/interfaces/i_bubble.js | 5 ++ core/interfaces/i_collapsible_toolbox_item.js | 5 ++ core/interfaces/i_component.js | 6 ++ core/interfaces/i_connection_checker.js | 6 ++ core/interfaces/i_contextmenu.js | 5 ++ core/interfaces/i_copyable.js | 5 ++ core/interfaces/i_deletable.js | 5 ++ core/interfaces/i_delete_area.js | 6 ++ core/interfaces/i_drag_target.js | 6 ++ core/interfaces/i_draggable.js | 5 ++ core/interfaces/i_flyout.js | 5 ++ core/interfaces/i_keyboard_accessible.js | 5 ++ core/interfaces/i_metrics_manager.js | 5 ++ core/interfaces/i_movable.js | 5 ++ core/interfaces/i_positionable.js | 5 ++ core/interfaces/i_registrable.js | 6 ++ core/interfaces/i_registrable_field.js | 4 + core/interfaces/i_selectable.js | 5 ++ core/interfaces/i_selectable_toolbox_item.js | 5 ++ core/interfaces/i_serializer.js | 8 +- core/interfaces/i_styleable.js | 5 ++ core/interfaces/i_toolbox.js | 5 ++ core/interfaces/i_toolbox_item.js | 5 ++ core/internal_constants.js | 31 +++++++ core/keyboard_nav/ast_node.js | 6 ++ core/keyboard_nav/basic_cursor.js | 6 ++ core/keyboard_nav/cursor.js | 6 ++ core/keyboard_nav/marker.js | 6 ++ core/keyboard_nav/tab_navigate_cursor.js | 6 ++ core/marker_manager.js | 5 ++ core/menu.js | 5 ++ core/menuitem.js | 5 ++ core/metrics_manager.js | 5 ++ core/msg.js | 4 +- core/mutator.js | 6 ++ core/names.js | 5 ++ core/options.js | 5 ++ core/positionable_helpers.js | 10 +++ core/procedures.js | 4 +- core/registry.js | 14 +++ core/rendered_connection.js | 5 ++ core/renderers/common/block_rendering.js | 9 ++ core/renderers/common/constants.js | 5 ++ core/renderers/common/debug.js | 7 ++ core/renderers/common/debugger.js | 7 +- core/renderers/common/drawer.js | 5 ++ core/renderers/common/i_path_object.js | 6 ++ core/renderers/common/info.js | 5 ++ core/renderers/common/marker_svg.js | 5 ++ core/renderers/common/path_object.js | 5 ++ core/renderers/common/renderer.js | 5 ++ core/renderers/geras/constants.js | 6 ++ core/renderers/geras/drawer.js | 5 ++ core/renderers/geras/geras.js | 4 + core/renderers/geras/highlight_constants.js | 5 ++ core/renderers/geras/highlighter.js | 6 ++ core/renderers/geras/info.js | 6 ++ .../geras/measurables/inline_input.js | 6 ++ .../geras/measurables/statement_input.js | 6 ++ core/renderers/geras/path_object.js | 5 ++ core/renderers/geras/renderer.js | 5 ++ core/renderers/measurables/base.js | 5 ++ core/renderers/measurables/bottom_row.js | 6 ++ core/renderers/measurables/connection.js | 6 ++ .../measurables/external_value_input.js | 6 ++ core/renderers/measurables/field.js | 6 ++ core/renderers/measurables/hat.js | 6 ++ core/renderers/measurables/icon.js | 6 ++ core/renderers/measurables/in_row_spacer.js | 6 ++ core/renderers/measurables/inline_input.js | 6 ++ .../renderers/measurables/input_connection.js | 5 ++ core/renderers/measurables/input_row.js | 6 ++ core/renderers/measurables/jagged_edge.js | 6 ++ core/renderers/measurables/next_connection.js | 6 ++ .../measurables/output_connection.js | 6 ++ .../measurables/previous_connection.js | 6 ++ core/renderers/measurables/round_corner.js | 6 ++ core/renderers/measurables/row.js | 5 ++ core/renderers/measurables/spacer_row.js | 5 ++ core/renderers/measurables/square_corner.js | 6 ++ core/renderers/measurables/statement_input.js | 6 ++ core/renderers/measurables/top_row.js | 5 ++ core/renderers/measurables/types.js | 5 ++ core/renderers/minimalist/constants.js | 6 ++ core/renderers/minimalist/drawer.js | 5 ++ core/renderers/minimalist/info.js | 5 ++ core/renderers/minimalist/minimalist.js | 4 + core/renderers/minimalist/renderer.js | 5 ++ core/renderers/thrasos/info.js | 6 ++ core/renderers/thrasos/renderer.js | 5 ++ core/renderers/thrasos/thrasos.js | 4 + core/renderers/zelos/constants.js | 6 ++ core/renderers/zelos/drawer.js | 5 ++ core/renderers/zelos/info.js | 5 ++ core/renderers/zelos/marker_svg.js | 5 ++ .../renderers/zelos/measurables/bottom_row.js | 5 ++ core/renderers/zelos/measurables/inputs.js | 6 ++ .../zelos/measurables/row_elements.js | 6 ++ core/renderers/zelos/measurables/top_row.js | 5 ++ core/renderers/zelos/path_object.js | 5 ++ core/renderers/zelos/renderer.js | 5 ++ core/renderers/zelos/zelos.js | 4 + core/scrollbar.js | 5 ++ core/scrollbar_pair.js | 5 ++ core/serialization/blocks.js | 12 ++- core/serialization/exceptions.js | 12 ++- core/serialization/priorities.js | 7 +- core/serialization/registry.js | 9 +- core/serialization/variables.js | 9 +- core/serialization/workspaces.js | 9 +- core/shortcut_items.js | 37 ++++++-- core/shortcut_registry.js | 6 ++ core/theme.js | 5 ++ core/theme/classic.js | 5 ++ core/theme/themes.js | 4 + core/theme/zelos.js | 4 + core/theme_manager.js | 6 ++ core/toolbox/category.js | 5 ++ core/toolbox/collapsible_category.js | 5 ++ core/toolbox/separator.js | 5 ++ core/toolbox/toolbox.js | 5 ++ core/toolbox/toolbox_item.js | 5 ++ core/tooltip.js | 9 +- core/touch.js | 15 ++++ core/touch_gesture.js | 6 ++ core/trashcan.js | 5 ++ core/utils.js | 6 +- core/utils/aria.js | 6 +- core/utils/colour.js | 6 +- core/utils/coordinate.js | 7 +- core/utils/deprecation.js | 5 +- core/utils/dom.js | 6 +- core/utils/global.js | 4 + core/utils/idgenerator.js | 5 +- core/utils/keycodes.js | 6 +- core/utils/math.js | 6 +- core/utils/metrics.js | 5 +- core/utils/object.js | 4 +- core/utils/rect.js | 7 +- core/utils/size.js | 7 +- core/utils/string.js | 6 +- core/utils/style.js | 6 +- core/utils/svg.js | 6 +- core/utils/svg_paths.js | 4 +- core/utils/toolbox.js | 4 +- core/utils/useragent.js | 6 +- core/utils/xml.js | 6 +- core/variable_map.js | 5 ++ core/variable_model.js | 5 ++ core/variables.js | 4 +- core/variables_dynamic.js | 7 ++ core/warning.js | 5 ++ core/widgetdiv.js | 8 +- core/workspace.js | 5 ++ core/workspace_audio.js | 6 ++ core/workspace_comment.js | 5 ++ core/workspace_comment_svg.js | 5 ++ core/workspace_drag_surface_svg.js | 8 ++ core/workspace_dragger.js | 5 ++ core/workspace_svg.js | 5 ++ core/xml.js | 17 ++++ core/zoom_controls.js | 5 ++ 252 files changed, 1533 insertions(+), 129 deletions(-) diff --git a/core/block.js b/core/block.js index 7654d2537..9ef639835 100644 --- a/core/block.js +++ b/core/block.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * The class representing one block. + * @namespace Blockly.Block + */ goog.module('Blockly.Block'); /* eslint-disable-next-line no-unused-vars */ @@ -67,6 +71,7 @@ goog.require('Blockly.Events.BlockMove'); * @implements {IASTNodeLocation} * @implements {IDeletable} * @throws When the prototypeName is not valid or not allowed. + * @alias Blockly.Block */ const Block = function(workspace, prototypeName, opt_id) { const Generator = goog.module.get('Blockly.Generator'); diff --git a/core/block_animations.js b/core/block_animations.js index ea8999a84..617fe4233 100644 --- a/core/block_animations.js +++ b/core/block_animations.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Methods animating a block on connection and disconnection. + * @namespace Blockly.blockAnimations + */ goog.module('Blockly.blockAnimations'); const Svg = goog.require('Blockly.utils.Svg'); @@ -33,6 +37,7 @@ let disconnectGroup = null; /** * Play some UI effects (sound, animation) when disposing of a block. * @param {!BlockSvg} block The block being disposed of. + * @alias Blockly.blockAnimations.disposeUiEffect */ const disposeUiEffect = function(block) { const workspace = block.workspace; @@ -83,6 +88,7 @@ const disposeUiStep = function(clone, rtl, start, workspaceScale) { /** * Play some UI effects (sound, ripple) after a connection has been established. * @param {!BlockSvg} block The block being connected. + * @alias Blockly.blockAnimations.connectionUiEffect */ const connectionUiEffect = function(block) { const workspace = block.workspace; @@ -138,6 +144,7 @@ const connectionUiStep = function(ripple, start, scale) { /** * Play some UI effects (sound, animation) when disconnecting a block. * @param {!BlockSvg} block The block being disconnected. + * @alias Blockly.blockAnimations.disconnectUiEffect */ const disconnectUiEffect = function(block) { block.workspace.getAudioManager().play('disconnect'); @@ -185,6 +192,7 @@ const disconnectUiStep = function(group, magnitude, start) { /** * Stop the disconnect UI animation immediately. + * @alias Blockly.blockAnimations.disconnectUiStop */ const disconnectUiStop = function() { if (disconnectGroup) { diff --git a/core/block_drag_surface.js b/core/block_drag_surface.js index 9cea21c39..8876e9e2d 100644 --- a/core/block_drag_surface.js +++ b/core/block_drag_surface.js @@ -16,6 +16,15 @@ 'use strict'; +/** + * A class that manages a surface for dragging blocks. When a + * block drag is started, we move the block (and children) to a separate DOM + * element that we move around using translate3d. At the end of the drag, the + * 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. + * @namespace Blockly.BlockDragSurfaceSvg + */ goog.module('Blockly.BlockDragSurfaceSvg'); const Coordinate = goog.require('Blockly.utils.Coordinate'); @@ -29,6 +38,7 @@ const utils = goog.require('Blockly.utils'); * SVG that contains only the currently moving block, or nothing. * @param {!Element} container Containing element. * @constructor + * @alias Blockly.BlockDragSurfaceSvg */ const BlockDragSurfaceSvg = function(container) { /** diff --git a/core/block_dragger.js b/core/block_dragger.js index 9e9c4e1cd..851189a1f 100644 --- a/core/block_dragger.js +++ b/core/block_dragger.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Methods for dragging a block visually. + * @namespace Blockly.BlockDragger + */ goog.module('Blockly.BlockDragger'); const Coordinate = goog.require('Blockly.utils.Coordinate'); @@ -41,6 +45,7 @@ goog.require('Blockly.Events.BlockMove'); * @param {!WorkspaceSvg} workspace The workspace to drag on. * @constructor * @implements {IBlockDragger} + * @alias Blockly.BlockDragger */ const BlockDragger = function(block, workspace) { /** diff --git a/core/block_svg.js b/core/block_svg.js index 838592305..2d3045ad9 100644 --- a/core/block_svg.js +++ b/core/block_svg.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Methods for graphically rendering a block as SVG. + * @namespace Blockly.BlockSvg + */ goog.module('Blockly.BlockSvg'); /* eslint-disable-next-line no-unused-vars */ @@ -89,6 +93,7 @@ goog.require('Blockly.Touch'); * @implements {ICopyable} * @implements {IDraggable} * @constructor + * @alias Blockly.BlockSvg */ const BlockSvg = function(workspace, prototypeName, opt_id) { // Create core elements for the block. diff --git a/core/blockly.js b/core/blockly.js index c39ae3e79..f8b81f652 100644 --- a/core/blockly.js +++ b/core/blockly.js @@ -5,7 +5,7 @@ */ /** - * @fileoverview Core JavaScript library for Blockly. + * @fileoverview The top level namespace used to access the Blockly library. * @author fraser@google.com (Neil Fraser) */ 'use strict'; diff --git a/core/blockly_options.js b/core/blockly_options.js index ef0dffc83..237a87f3c 100644 --- a/core/blockly_options.js +++ b/core/blockly_options.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Object that defines user-specified options for the workspace. + * @namespace Blockly.BlocklyOptions + */ goog.module('Blockly.BlocklyOptions'); @@ -18,6 +22,7 @@ goog.module('Blockly.BlocklyOptions'); * This interface is further described in * `typings/parts/blockly-interfaces.d.ts`. * @interface + * @alias Blockly.BlocklyOptions */ const BlocklyOptions = function() {}; diff --git a/core/blocks.js b/core/blocks.js index 7bd3362ea..6b632b3af 100644 --- a/core/blocks.js +++ b/core/blocks.js @@ -12,7 +12,7 @@ /** * A mapping of block type names to block prototype objects. - * @name Blockly.Blocks + * @namespace Blockly.blocks */ goog.module('Blockly.blocks'); @@ -20,6 +20,7 @@ goog.module('Blockly.blocks'); /** * A mapping of block type names to block prototype objects. * @type {!Object} + * @alias Blockly.blocks.Blocks */ const Blocks = Object.create(null); diff --git a/core/browser_events.js b/core/browser_events.js index 2d70dcf0a..483e214c0 100644 --- a/core/browser_events.js +++ b/core/browser_events.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Browser event handling. + * @namespace Blockly.browserEvents + */ goog.module('Blockly.browserEvents'); const Touch = goog.require('Blockly.Touch'); @@ -22,6 +26,7 @@ const userAgent = goog.require('Blockly.utils.userAgent'); * Blockly opaque event data used to unbind events when using * `bind` and `conditionalBind`. * @typedef {!Array} + * @alias Blockly.browserEvents.Data */ let Data; exports.Data = Data; @@ -44,6 +49,7 @@ exports.Data = Data; * provided. * @return {!Data} Opaque data that can be passed to * unbindEvent_. + * @alias Blockly.browserEvents.conditionalBind */ const conditionalBind = function( node, name, thisObject, func, opt_noCaptureIdentifier, @@ -114,6 +120,7 @@ exports.conditionalBind = conditionalBind; * @param {!Function} func Function to call when event is triggered. * @return {!Data} Opaque data that can be passed to * unbindEvent_. + * @alias Blockly.browserEvents.bind */ const bind = function(node, name, thisObject, func) { const wrapFunc = function(e) { @@ -166,6 +173,7 @@ exports.bind = bind; * @param {!Data} bindData Opaque data from bindEvent_. * This list is emptied during the course of calling this function. * @return {!Function} The function call. + * @alias Blockly.browserEvents.unbind */ const unbind = function(bindData) { let func; @@ -184,6 +192,7 @@ exports.unbind = unbind; * Returns true if this event is targeting a text input widget? * @param {!Event} e An event. * @return {boolean} True if text input. + * @alias Blockly.browserEvents.isTargetInput */ const isTargetInput = function(e) { return e.target.type == 'textarea' || e.target.type == 'text' || @@ -199,6 +208,7 @@ exports.isTargetInput = isTargetInput; * Returns true this event is a right-click. * @param {!Event} e Mouse event. * @return {boolean} True if right-click. + * @alias Blockly.browserEvents.isRightButton */ const isRightButton = function(e) { if (e.ctrlKey && userAgent.MAC) { @@ -217,6 +227,7 @@ exports.isRightButton = isRightButton; * @param {!Element} svg SVG element. * @param {?SVGMatrix} matrix Inverted screen CTM to use. * @return {!SVGPoint} Object with .x and .y properties. + * @alias Blockly.browserEvents.mouseToSvg */ const mouseToSvg = function(e, svg, matrix) { const svgPoint = svg.createSVGPoint(); @@ -235,6 +246,7 @@ exports.mouseToSvg = mouseToSvg; * @param {!Event} e Mouse event. * @return {{x: number, y: number}} Scroll delta object with .x and .y * properties. + * @alias Blockly.browserEvents.getScrollDeltaPixels */ const getScrollDeltaPixels = function(e) { switch (e.deltaMode) { diff --git a/core/bubble.js b/core/bubble.js index a4581cdb9..7519fdea2 100644 --- a/core/bubble.js +++ b/core/bubble.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Object representing a UI bubble. + * @namespace Blockly.Bubble + */ goog.module('Blockly.Bubble'); const Coordinate = goog.require('Blockly.utils.Coordinate'); @@ -47,6 +51,7 @@ goog.require('Blockly.Workspace'); * @param {?number} bubbleHeight Height of bubble, or null if not resizable. * @implements {IBubble} * @constructor + * @alias Blockly.Bubble */ const Bubble = function( workspace, content, shape, anchorXY, bubbleWidth, bubbleHeight) { diff --git a/core/bubble_dragger.js b/core/bubble_dragger.js index 83aadb24b..cd256c7ed 100644 --- a/core/bubble_dragger.js +++ b/core/bubble_dragger.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Methods for dragging a bubble visually. + * @namespace Blockly.BubbleDragger + */ goog.module('Blockly.BubbleDragger'); const ComponentManager = goog.require('Blockly.ComponentManager'); @@ -43,6 +47,7 @@ goog.require('Blockly.constants'); * @param {!IBubble} bubble The item on the bubble canvas to drag. * @param {!WorkspaceSvg} workspace The workspace to drag on. * @constructor + * @alias Blockly.BubbleDragger */ const BubbleDragger = function(bubble, workspace) { /** diff --git a/core/bump_objects.js b/core/bump_objects.js index 80f42ab91..125fd6c91 100644 --- a/core/bump_objects.js +++ b/core/bump_objects.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Utilities for bumping objects back into worksapce bounds. + * @namespace Blockly.bumpObjects + */ goog.module('Blockly.bumpObjects'); /* eslint-disable-next-line no-unused-vars */ @@ -37,6 +41,7 @@ const {BlockSvg} = goog.requireType('Blockly.BlockSvg'); * in workspace coordinates. * @param {!IBoundedElement} object The object to bump. * @return {boolean} True if block was bumped. + * @alias Blockly.bumpObjects.bumpIntoBounds */ const bumpObjectIntoBounds = function(workspace, scrollMetrics, object) { // Compute new top/left position for object. @@ -85,6 +90,7 @@ exports.bumpIntoBounds = bumpObjectIntoBounds; * Creates a handler for bumping objects when they cross fixed bounds. * @param {!WorkspaceSvg} workspace The workspace to handle. * @return {function(Abstract)} The event handler. + * @alias Blockly.bumpObjects.bumpIntoBoundsHandler */ const bumpIntoBoundsHandler = function(workspace) { return function(e) { @@ -158,6 +164,7 @@ const extractObjectFromEvent = function(workspace, e) { /** * Bumps the top objects in the given workspace into bounds. * @param {!WorkspaceSvg} workspace The workspace. + * @alias Blockly.bumpObjects.bumpTopObjectsIntoBounds */ const bumpTopObjectsIntoBounds = function(workspace) { const metricsManager = workspace.getMetricsManager(); diff --git a/core/clipboard.js b/core/clipboard.js index 33a1b9c24..b359bc3b4 100644 --- a/core/clipboard.js +++ b/core/clipboard.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Blockly's internal clipboard for managing copy-paste. + * @namespace Blockly.clipboard + */ goog.module('Blockly.clipboard'); /* eslint-disable-next-line no-unused-vars */ @@ -26,6 +30,7 @@ let copyData = null; /** * Copy a block or workspace comment onto the local clipboard. * @param {!ICopyable} toCopy Block or Workspace Comment to be copied. + * @alias Blockly.clipboard.copy */ const copy = function(toCopy) { copyData = toCopy.toCopyData(); @@ -36,6 +41,7 @@ exports.copy = copy; /** * Paste a block or workspace comment on to the main workspace. * @return {boolean} True if the paste was successful, false otherwise. + * @alias Blockly.clipboard.paste */ const paste = function() { if (!copyData) { @@ -63,6 +69,7 @@ exports.paste = paste; * Duplicate this block and its children, or a workspace comment. * @param {!ICopyable} toDuplicate Block or Workspace Comment to be * duplicated. + * @alias Blockly.clipboard.duplicate */ const duplicate = function(toDuplicate) { const oldCopyData = copyData; diff --git a/core/comment.js b/core/comment.js index 149b9f65d..c7d667b4c 100644 --- a/core/comment.js +++ b/core/comment.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Object representing a code comment. + * @namespace Blockly.Comment + */ goog.module('Blockly.Comment'); const Bubble = goog.require('Blockly.Bubble'); @@ -44,6 +48,7 @@ goog.require('Blockly.Warning'); * @param {!Block} block The block associated with this comment. * @extends {Icon} * @constructor + * @alias Blockly.Comment */ const Comment = function(block) { Comment.superClass_.constructor.call(this, block); diff --git a/core/common.js b/core/common.js index 85f611f6e..d1a0e2ac2 100644 --- a/core/common.js +++ b/core/common.js @@ -11,6 +11,11 @@ */ 'use strict'; +/** + * Common functions used both internally and externally, but which + * must not be at the top level to avoid circular dependencies. + * @namespace Blockly.common + */ goog.module('Blockly.common'); /* eslint-disable-next-line no-unused-vars */ @@ -35,6 +40,7 @@ let mainWorkspace; * this function, particularly if there are multiple Blockly instances on a * page. * @return {!Workspace} The main workspace. + * @alias Blockly.common.getMainWorkspace */ const getMainWorkspace = function() { return mainWorkspace; @@ -44,6 +50,7 @@ exports.getMainWorkspace = getMainWorkspace; /** * Sets last used main workspace. * @param {!Workspace} workspace The most recently used top level workspace. + * @alias Blockly.common.setMainWorkspace */ const setMainWorkspace = function(workspace) { mainWorkspace = workspace; @@ -59,6 +66,7 @@ let selected = null; /** * Returns the currently selected block. * @return {?ICopyable} The currently selected block. + * @alias Blockly.common.getSelected */ const getSelected = function() { return selected; @@ -68,6 +76,7 @@ exports.getSelected = getSelected; /** * Sets the currently selected block. * @param {?ICopyable} newSelection The newly selected block. + * @alias Blockly.common.setSelected */ const setSelected = function(newSelection) { selected = newSelection; @@ -84,6 +93,7 @@ let parentContainer; * Get the container element in which to render the WidgetDiv, DropDownDiv and\ * Tooltip. * @return {?Element} The parent container. + * @alias Blockly.common.getParentContainer */ const getParentContainer = function() { return parentContainer; @@ -96,6 +106,7 @@ exports.getParentContainer = getParentContainer; * is called. * This method is a NOP if called after the first ``Blockly.inject``. * @param {!Element} newParent The container element. + * @alias Blockly.common.setParentContainer */ const setParentContainer = function(newParent) { parentContainer = newParent; @@ -109,6 +120,7 @@ exports.setParentContainer = setParentContainer; * change (e.g. when a block is added or removed). * Record the height/width of the SVG image. * @param {!WorkspaceSvg} workspace Any workspace in the SVG. + * @alias Blockly.common.svgResize */ const svgResize = function(workspace) { let mainWorkspace = workspace; diff --git a/core/component_manager.js b/core/component_manager.js index 33c7e6784..f667f3685 100644 --- a/core/component_manager.js +++ b/core/component_manager.js @@ -11,6 +11,10 @@ 'use strict'; +/** + * Manager for all items registered with the workspace. + * @namespace Blockly.ComponentManager + */ goog.module('Blockly.ComponentManager'); /* eslint-disable-next-line no-unused-vars */ @@ -29,6 +33,7 @@ const utils = goog.require('Blockly.utils'); /** * Manager for all items registered with the workspace. * @constructor + * @alias Blockly.ComponentManager */ const ComponentManager = function() { /** diff --git a/core/connection.js b/core/connection.js index 30dcab1f9..16af039a3 100644 --- a/core/connection.js +++ b/core/connection.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Components for creating connections between blocks. + * @namespace Blockly.Connection + */ goog.module('Blockly.Connection'); /* eslint-disable-next-line no-unused-vars */ @@ -37,6 +41,7 @@ goog.require('Blockly.Events.BlockMove'); * @param {number} type The type of the connection. * @constructor * @implements {IASTNodeLocationWithBlock} + * @alias Blockly.Connection */ const Connection = function(source, type) { /** diff --git a/core/connection_checker.js b/core/connection_checker.js index 3395b4bac..166d46e8a 100644 --- a/core/connection_checker.js +++ b/core/connection_checker.js @@ -11,6 +11,11 @@ */ 'use strict'; +/** + * An object that encapsulates logic for checking whether a + * potential connection is safe and valid. + * @namespace Blockly.ConnectionChecker + */ goog.module('Blockly.ConnectionChecker'); const Connection = goog.require('Blockly.Connection'); @@ -28,6 +33,7 @@ const {ConnectionType} = goog.require('Blockly.ConnectionType'); * Class for connection type checking logic. * @implements {IConnectionChecker} * @constructor + * @alias Blockly.ConnectionChecker */ const ConnectionChecker = function() {}; diff --git a/core/connection_db.js b/core/connection_db.js index e745a2392..72e8c09ff 100644 --- a/core/connection_db.js +++ b/core/connection_db.js @@ -12,6 +12,12 @@ */ 'use strict'; +/** + * A database of all the rendered connections that could + * possibly be connected to (i.e. not collapsed, etc). + * Sorted by y coordinate. + * @namespace Blockly.ConnectionDB + */ goog.module('Blockly.ConnectionDB'); /* eslint-disable-next-line no-unused-vars */ @@ -33,6 +39,7 @@ goog.require('Blockly.constants'); * connection type checker, used to decide if connections are valid during a * drag. * @constructor + * @alias Blockly.ConnectionDB */ const ConnectionDB = function(checker) { /** diff --git a/core/connection_type.js b/core/connection_type.js index 607e20047..4f6810a15 100644 --- a/core/connection_type.js +++ b/core/connection_type.js @@ -11,12 +11,17 @@ 'use strict'; +/** + * An enum for the possible types of connections. + * @namespace Blockly.ConnectionType + */ goog.module('Blockly.ConnectionType'); /** * Enum for the type of a connection or input. * @enum {number} + * @alias Blockly.ConnectionType */ const ConnectionType = { // A right-facing value input. E.g. 'set item to' or 'return'. diff --git a/core/constants.js b/core/constants.js index 3a247c17f..d9f3c9595 100644 --- a/core/constants.js +++ b/core/constants.js @@ -10,12 +10,17 @@ */ 'use strict'; +/** + * Blockly constants. + * @namespace Blockly.constants + */ goog.module('Blockly.constants'); /** * Enum for alignment of inputs. * @enum {number} + * @alias Blockly.constants.ALIGN */ const ALIGN = { LEFT: -1, @@ -27,6 +32,7 @@ exports.ALIGN = ALIGN; /** * The language-neutral ID given to the collapsed input. * @const {string} + * @alias Blockly.constants.COLLAPSED_INPUT_NAME */ const COLLAPSED_INPUT_NAME = '_TEMP_COLLAPSED_INPUT'; exports.COLLAPSED_INPUT_NAME = COLLAPSED_INPUT_NAME; @@ -34,6 +40,7 @@ exports.COLLAPSED_INPUT_NAME = COLLAPSED_INPUT_NAME; /** * The language-neutral ID given to the collapsed field. * @const {string} + * @alias Blockly.constants.COLLAPSED_FIELD_NAME */ const COLLAPSED_FIELD_NAME = '_TEMP_COLLAPSED_FIELD'; exports.COLLAPSED_FIELD_NAME = COLLAPSED_FIELD_NAME; diff --git a/core/contextmenu.js b/core/contextmenu.js index 274b2a6e4..d1c4aecba 100644 --- a/core/contextmenu.js +++ b/core/contextmenu.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Functionality for the right-click context menus. + * @namespace Blockly.ContextMenu + */ goog.module('Blockly.ContextMenu'); /* eslint-disable-next-line no-unused-vars */ @@ -47,6 +51,7 @@ let currentBlock = null; /** * Gets the block the context menu is currently attached to. * @return {?Block} The block the context menu is attached to. + * @alias Blockly.ContextMenu.getCurrentBlock */ const getCurrentBlock = function() { return currentBlock; @@ -56,6 +61,7 @@ exports.getCurrentBlock = getCurrentBlock; /** * Sets the block the context menu is currently attached to. * @param {?Block} block The block the context menu is attached to. + * @alias Blockly.ContextMenu.setCurrentBlock */ const setCurrentBlock = function(block) { currentBlock = block; @@ -91,6 +97,7 @@ let menu_ = null; * @param {!Event} e Mouse event. * @param {!Array} options Array of menu options. * @param {boolean} rtl True if RTL, false if LTR. + * @alias Blockly.ContextMenu.show */ const show = function(e, options, rtl) { WidgetDiv.show(exports, rtl, dispose); @@ -215,6 +222,7 @@ const haltPropagation = function(e) { /** * Hide the context menu. + * @alias Blockly.ContextMenu.hide */ const hide = function() { WidgetDiv.hideIfOwner(exports); @@ -224,6 +232,7 @@ exports.hide = hide; /** * Dispose of the menu. + * @alias Blockly.ContextMenu.dispose */ const dispose = function() { if (menu_) { @@ -239,6 +248,7 @@ exports.dispose = dispose; * @param {!Block} block Original block. * @param {!Element} xml XML representation of new block. * @return {!Function} Function that creates a block. + * @alias Blockly.ContextMenu.callbackFactory */ const callbackFactory = function(block, xml) { return function() { @@ -273,6 +283,7 @@ exports.callbackFactory = callbackFactory; * @param {!WorkspaceCommentSvg} comment The workspace comment where the * right-click originated. * @return {!Object} A menu option, containing text, enabled, and a callback. + * @alias Blockly.ContextMenu.commentDeleteOption */ const commentDeleteOption = function(comment) { const deleteOption = { @@ -294,6 +305,7 @@ exports.commentDeleteOption = commentDeleteOption; * @param {!WorkspaceCommentSvg} comment The workspace comment where the * right-click originated. * @return {!Object} A menu option, containing text, enabled, and a callback. + * @alias Blockly.ContextMenu.commentDuplicateOption */ const commentDuplicateOption = function(comment) { const duplicateOption = { @@ -317,6 +329,7 @@ exports.commentDuplicateOption = commentDuplicateOption; * @package * @suppress {strictModuleDepCheck,checkTypes} Suppress checks while workspace * comments are not bundled in. + * @alias Blockly.ContextMenu.workspaceCommentOption */ const workspaceCommentOption = function(ws, e) { const WorkspaceCommentSvg = goog.module.get('Blockly.WorkspaceCommentSvg'); diff --git a/core/contextmenu_items.js b/core/contextmenu_items.js index f8af8893d..14727e2bf 100644 --- a/core/contextmenu_items.js +++ b/core/contextmenu_items.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Registers default context menu items. + * @namespace Blockly.ContextMenuItems + */ goog.module('Blockly.ContextMenuItems'); const ContextMenuRegistry = goog.require('Blockly.ContextMenuRegistry'); @@ -26,7 +30,10 @@ const userAgent = goog.require('Blockly.utils.userAgent'); const {BlockSvg} = goog.requireType('Blockly.BlockSvg'); -/** Option to undo previous action. */ +/** + * Option to undo previous action. + * @alias Blockly.ContextMenuItems.registerUndo + */ const registerUndo = function() { /** @type {!ContextMenuRegistry.RegistryItem} */ const undoOption = { @@ -52,7 +59,10 @@ const registerUndo = function() { }; exports.registerUndo = registerUndo; -/** Option to redo previous action. */ +/** + * Option to redo previous action. + * @alias Blockly.ContextMenuItems.registerRedo + */ const registerRedo = function() { /** @type {!ContextMenuRegistry.RegistryItem} */ const redoOption = { @@ -78,7 +88,10 @@ const registerRedo = function() { }; exports.registerRedo = registerRedo; -/** Option to clean up blocks. */ +/** + * Option to clean up blocks. + * @alias Blockly.ContextMenuItems.registerCleanup + */ const registerCleanup = function() { /** @type {!ContextMenuRegistry.RegistryItem} */ const cleanOption = { @@ -126,7 +139,10 @@ const toggleOption_ = function(shouldCollapse, topBlocks) { } }; -/** Option to collapse all blocks. */ +/** + * Option to collapse all blocks. + * @alias Blockly.ContextMenuItems.registerCollapse + */ const registerCollapse = function() { /** @type {!ContextMenuRegistry.RegistryItem} */ const collapseOption = { @@ -162,7 +178,10 @@ const registerCollapse = function() { }; exports.registerCollapse = registerCollapse; -/** Option to expand all blocks. */ +/** + * Option to expand all blocks. + * @alias Blockly.ContextMenuItems.registerExpand + */ const registerExpand = function() { /** @type {!ContextMenuRegistry.RegistryItem} */ const expandOption = { @@ -255,7 +274,10 @@ const deleteNext_ = function(deleteList, eventGroup) { eventUtils.setGroup(false); }; -/** Option to delete all blocks. */ +/** + * Option to delete all blocks. + * @alias Blockly.ContextMenuItems.registerDeleteAll + */ const registerDeleteAll = function() { /** @type {!ContextMenuRegistry.RegistryItem} */ const deleteOption = { @@ -321,7 +343,10 @@ const registerWorkspaceOptions_ = function() { registerDeleteAll(); }; -/** Option to duplicate a block. */ +/** + * Option to duplicate a block. + * @alias Blockly.ContextMenuItems.registerDuplicate + */ const registerDuplicate = function() { /** @type {!ContextMenuRegistry.RegistryItem} */ const duplicateOption = { @@ -353,7 +378,10 @@ const registerDuplicate = function() { }; exports.registerDuplicate = registerDuplicate; -/** Option to add or remove block-level comment. */ +/** + * Option to add or remove block-level comment. + * @alias Blockly.ContextMenuItems.registerComment + */ const registerComment = function() { /** @type {!ContextMenuRegistry.RegistryItem} */ const commentOption = { @@ -394,7 +422,10 @@ const registerComment = function() { }; exports.registerComment = registerComment; -/** Option to inline variables. */ +/** + * Option to inline variables. + * @alias Blockly.ContextMenuItems.registerInline + */ const registerInline = function() { /** @type {!ContextMenuRegistry.RegistryItem} */ const inlineOption = { @@ -430,7 +461,10 @@ const registerInline = function() { }; exports.registerInline = registerInline; -/** Option to collapse or expand a block. */ +/** + * Option to collapse or expand a block. + * @alias Blockly.ContextMenuItems.registerCollapseExpandBlock + */ const registerCollapseExpandBlock = function() { /** @type {!ContextMenuRegistry.RegistryItem} */ const collapseExpandOption = { @@ -460,7 +494,10 @@ const registerCollapseExpandBlock = function() { }; exports.registerCollapseExpandBlock = registerCollapseExpandBlock; -/** Option to disable or enable a block. */ +/** + * Option to disable or enable a block. + * @alias Blockly.ContextMenuItems.registerDisable + */ const registerDisable = function() { /** @type {!ContextMenuRegistry.RegistryItem} */ const disableOption = { @@ -501,7 +538,10 @@ const registerDisable = function() { }; exports.registerDisable = registerDisable; -/** Option to delete a block. */ +/** + * Option to delete a block. + * @alias Blockly.ContextMenuItems.registerDelete + */ const registerDelete = function() { /** @type {!ContextMenuRegistry.RegistryItem} */ const deleteOption = { @@ -540,7 +580,10 @@ const registerDelete = function() { }; exports.registerDelete = registerDelete; -/** Option to open help for a block. */ +/** + * Option to open help for a block. + * @alias Blockly.ContextMenuItems.registerHelp + */ const registerHelp = function() { /** @type {!ContextMenuRegistry.RegistryItem} */ const helpOption = { @@ -587,6 +630,7 @@ const registerBlockOptions_ = function() { * Registers all default context menu items. This should be called once per * instance of ContextMenuRegistry. * @package + * @alias Blockly.ContextMenuItems.registerDefaultOptions */ const registerDefaultOptions = function() { registerWorkspaceOptions_(); diff --git a/core/contextmenu_registry.js b/core/contextmenu_registry.js index 48daec7f6..a87492836 100644 --- a/core/contextmenu_registry.js +++ b/core/contextmenu_registry.js @@ -11,8 +11,8 @@ 'use strict'; /** - * @name ContextMenuRegistry - * @namespace + * Registry for context menu option items. + * @namespace Blockly.ContextMenuRegistry */ goog.module('Blockly.ContextMenuRegistry'); @@ -28,6 +28,7 @@ const {BlockSvg} = goog.requireType('Blockly.BlockSvg'); * from ContextMenuRegistry.registry. * @constructor * @private + * @alias Blockly.ContextMenuRegistry */ const ContextMenuRegistry = function() { // Singleton instance should be registered once. diff --git a/core/css.js b/core/css.js index 0e0b7fa5f..9b6c9b2f9 100644 --- a/core/css.js +++ b/core/css.js @@ -11,8 +11,8 @@ 'use strict'; /** - * @name Blockly.Css - * @namespace + * Inject Blockly's CSS synchronously. + * @namespace Blockly.Css */ goog.module('Blockly.Css'); diff --git a/core/delete_area.js b/core/delete_area.js index 67e22d685..78b26ad64 100644 --- a/core/delete_area.js +++ b/core/delete_area.js @@ -12,6 +12,11 @@ 'use strict'; +/** + * The abstract class for a component that can delete a block or + * bubble that is dropped on top of it. + * @namespace Blockly.DeleteArea + */ goog.module('Blockly.DeleteArea'); const DragTarget = goog.require('Blockly.DragTarget'); @@ -29,6 +34,7 @@ const {BlockSvg} = goog.require('Blockly.BlockSvg'); * @extends {DragTarget} * @implements {IDeleteArea} * @constructor + * @alias Blockly.DeleteArea */ const DeleteArea = function() { DeleteArea.superClass_.constructor.call(this); diff --git a/core/dialog.js b/core/dialog.js index fe387065a..9356a984c 100644 --- a/core/dialog.js +++ b/core/dialog.js @@ -11,6 +11,10 @@ 'use strict'; +/** + * Wrapper functions around JS functions for showing alert/confirmation dialogs. + * @namespace Blockly.dialog + */ goog.module('Blockly.dialog'); let alertImplementation = function(message, opt_callback) { @@ -33,6 +37,7 @@ let promptImplementation = function(message, defaultValue, callback) { * provide alternatives to the modal browser window. * @param {string} message The message to display to the user. * @param {function()=} opt_callback The callback when the alert is dismissed. + * @alias Blockly.dialog.alert */ const alert = function(message, opt_callback) { alertImplementation(message, opt_callback); @@ -43,6 +48,7 @@ exports.alert = alert; * Sets the function to be run when Blockly.dialog.alert() is called. * @param {!function(string, function()=)} alertFunction The function to be run. * @see Blockly.dialog.alert + * @alias Blockly.dialog.setAlert */ const setAlert = function(alertFunction) { alertImplementation = alertFunction; @@ -54,6 +60,7 @@ exports.setAlert = setAlert; * to provide alternatives to the modal browser window. * @param {string} message The message to display to the user. * @param {!function(boolean)} callback The callback for handling user response. + * @alias Blockly.dialog.confirm */ const confirm = function(message, callback) { confirmImplementation(message, callback); @@ -65,6 +72,7 @@ exports.confirm = confirm; * @param {!function(string, !function(boolean))} confirmFunction The function * to be run. * @see Blockly.dialog.confirm + * @alias Blockly.dialog.setConfirm */ const setConfirm = function(confirmFunction) { confirmImplementation = confirmFunction; @@ -79,6 +87,7 @@ exports.setConfirm = setConfirm; * @param {string} message The message to display to the user. * @param {string} defaultValue The value to initialize the prompt with. * @param {!function(?string)} callback The callback for handling user response. + * @alias Blockly.dialog.prompt */ const prompt = function(message, defaultValue, callback) { promptImplementation(message, defaultValue, callback); @@ -90,6 +99,7 @@ exports.prompt = prompt; * @param {!function(string, string, !function(?string))} promptFunction The * function to be run. * @see Blockly.dialog.prompt + * @alias Blockly.dialog.setPrompt */ const setPrompt = function(promptFunction) { promptImplementation = promptFunction; diff --git a/core/drag_target.js b/core/drag_target.js index daec4cf89..33403c853 100644 --- a/core/drag_target.js +++ b/core/drag_target.js @@ -12,6 +12,11 @@ 'use strict'; +/** + * The abstract class for a component with custom behaviour when a + * block or bubble is dragged over or dropped on top of it. + * @namespace Blockly.DragTarget + */ goog.module('Blockly.DragTarget'); /* eslint-disable-next-line no-unused-vars */ @@ -27,6 +32,7 @@ const Rect = goog.requireType('Blockly.utils.Rect'); * is dragged over or dropped on top of it. * @implements {IDragTarget} * @constructor + * @alias Blockly.DragTarget */ const DragTarget = function() {}; diff --git a/core/dropdowndiv.js b/core/dropdowndiv.js index c5517bf3e..25187abb4 100644 --- a/core/dropdowndiv.js +++ b/core/dropdowndiv.js @@ -13,6 +13,10 @@ 'use strict'; +/** + * A div that floats on top of the workspace, for drop-down menus. + * @namespace Blockly.DropDownDiv + */ goog.module('Blockly.DropDownDiv'); const Rect = goog.require('Blockly.utils.Rect'); @@ -34,6 +38,7 @@ const {BlockSvg} = goog.requireType('Blockly.BlockSvg'); * Class for drop-down div. * @constructor * @package + * @alias Blockly.DropDownDiv */ const DropDownDiv = function() {}; diff --git a/core/events/events_abstract.js b/core/events/events_abstract.js index 051ea4960..3a0a9e006 100644 --- a/core/events/events_abstract.js +++ b/core/events/events_abstract.js @@ -6,11 +6,16 @@ /** * @fileoverview Abstract class for events fired as a result of actions in - * Blockly's editor. + * Blockly's editor. * @author fraser@google.com (Neil Fraser) */ 'use strict'; +/** + * Abstract class for events fired as a result of actions in + * Blockly's editor. + * @namespace Blockly.Events.Abstract + */ goog.module('Blockly.Events.Abstract'); const eventUtils = goog.require('Blockly.Events.utils'); @@ -21,6 +26,7 @@ const Workspace = goog.requireType('Blockly.Workspace'); /** * Abstract class for an event. * @constructor + * @alias Blockly.Events.Abstract */ const Abstract = function() { /** diff --git a/core/events/events_block_base.js b/core/events/events_block_base.js index 62769dc2b..7cbdd9634 100644 --- a/core/events/events_block_base.js +++ b/core/events/events_block_base.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Base class for all types of block events. + * @namespace Blockly.Events.BlockBase + */ goog.module('Blockly.Events.BlockBase'); const Abstract = goog.require('Blockly.Events.Abstract'); @@ -24,6 +28,7 @@ const {Block} = goog.requireType('Blockly.Block'); * Undefined for a blank event. * @extends {Abstract} * @constructor + * @alias Blockly.Events.BlockBase */ const BlockBase = function(opt_block) { BlockBase.superClass_.constructor.call(this); diff --git a/core/events/events_block_change.js b/core/events/events_block_change.js index 526d09bc6..922fe6fc5 100644 --- a/core/events/events_block_change.js +++ b/core/events/events_block_change.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Class for a block change event. + * @namespace Blockly.Events.BlockChange + */ goog.module('Blockly.Events.BlockChange'); const BlockBase = goog.require('Blockly.Events.BlockBase'); @@ -33,6 +37,7 @@ const {BlockSvg} = goog.requireType('Blockly.BlockSvg'); * @param {*=} opt_newValue New value of element. * @extends {BlockBase} * @constructor + * @alias Blockly.Events.BlockChange */ const BlockChange = function( opt_block, opt_element, opt_name, opt_oldValue, opt_newValue) { diff --git a/core/events/events_block_create.js b/core/events/events_block_create.js index acf9e8824..c384ea41d 100644 --- a/core/events/events_block_create.js +++ b/core/events/events_block_create.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Class for a block creation event. + * @namespace Blockly.Events.BlockCreate + */ goog.module('Blockly.Events.BlockCreate'); const BlockBase = goog.require('Blockly.Events.BlockBase'); @@ -28,6 +32,7 @@ const {Block} = goog.requireType('Blockly.Block'); * event. * @extends {BlockBase} * @constructor + * @alias Blockly.Events.BlockCreate */ const BlockCreate = function(opt_block) { BlockCreate.superClass_.constructor.call(this, opt_block); diff --git a/core/events/events_block_delete.js b/core/events/events_block_delete.js index 5a7e03cc6..09fc27d6d 100644 --- a/core/events/events_block_delete.js +++ b/core/events/events_block_delete.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Class for a block delete event. + * @namespace Blockly.Events.BlockDelete + */ goog.module('Blockly.Events.BlockDelete'); const BlockBase = goog.require('Blockly.Events.BlockBase'); @@ -28,6 +32,7 @@ const {Block} = goog.requireType('Blockly.Block'); * event. * @extends {BlockBase} * @constructor + * @alias Blockly.Events.BlockDelete */ const BlockDelete = function(opt_block) { BlockDelete.superClass_.constructor.call(this, opt_block); diff --git a/core/events/events_block_drag.js b/core/events/events_block_drag.js index 3e36d6588..938abeab0 100644 --- a/core/events/events_block_drag.js +++ b/core/events/events_block_drag.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Events fired as a block drag. + * @namespace Blockly.Events.BlockDrag + */ goog.module('Blockly.Events.BlockDrag'); const UiBase = goog.require('Blockly.Events.UiBase'); @@ -30,6 +34,7 @@ const {Block} = goog.requireType('Blockly.Block'); * drag. Undefined for a blank event. * @extends {UiBase} * @constructor + * @alias Blockly.Events.BlockDrag */ const BlockDrag = function(opt_block, opt_isStart, opt_blocks) { const workspaceId = opt_block ? opt_block.workspace.id : undefined; diff --git a/core/events/events_block_move.js b/core/events/events_block_move.js index 036c97a64..999f2eecc 100644 --- a/core/events/events_block_move.js +++ b/core/events/events_block_move.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Class for a block move event. + * @namespace Blockly.Events.BlockMove + */ goog.module('Blockly.Events.BlockMove'); const BlockBase = goog.require('Blockly.Events.BlockBase'); @@ -28,6 +32,7 @@ const {ConnectionType} = goog.require('Blockly.ConnectionType'); * event. * @extends {BlockBase} * @constructor + * @alias Blockly.Events.BlockMove */ const BlockMove = function(opt_block) { BlockMove.superClass_.constructor.call(this, opt_block); diff --git a/core/events/events_bubble_open.js b/core/events/events_bubble_open.js index dd4611ffe..753d27298 100644 --- a/core/events/events_bubble_open.js +++ b/core/events/events_bubble_open.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Events fired as a result of bubble open. + * @namespace Blockly.Events.BubbleOpen + */ goog.module('Blockly.Events.BubbleOpen'); const UiBase = goog.require('Blockly.Events.UiBase'); @@ -31,6 +35,7 @@ const {BlockSvg} = goog.requireType('Blockly.BlockSvg'); * or 'warning'. Undefined for a blank event. * @extends {UiBase} * @constructor + * @alias Blockly.Events.BubbleOpen */ const BubbleOpen = function(opt_block, opt_isOpen, opt_bubbleType) { const workspaceId = opt_block ? opt_block.workspace.id : undefined; diff --git a/core/events/events_click.js b/core/events/events_click.js index ea64c7446..8dabf1a49 100644 --- a/core/events/events_click.js +++ b/core/events/events_click.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Events fired as a result of UI click in Blockly's editor. + * @namespace Blockly.Events.Click + */ goog.module('Blockly.Events.Click'); const UiBase = goog.require('Blockly.Events.UiBase'); @@ -31,6 +35,7 @@ const {Block} = goog.requireType('Blockly.Block'); * event. Undefined for a blank event. * @extends {UiBase} * @constructor + * @alias Blockly.Events.Click */ const Click = function(opt_block, opt_workspaceId, opt_targetType) { const workspaceId = opt_block ? opt_block.workspace.id : opt_workspaceId; diff --git a/core/events/events_comment_base.js b/core/events/events_comment_base.js index a3ecd866c..8b2df24c3 100644 --- a/core/events/events_comment_base.js +++ b/core/events/events_comment_base.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Base class for comment events. + * @namespace Blockly.Events.CommentBase + */ goog.module('Blockly.Events.CommentBase'); const AbstractEvents = goog.require('Blockly.Events.Abstract'); @@ -31,6 +35,7 @@ const utilsXml = goog.require('Blockly.utils.xml'); * corresponds to. Undefined for a blank event. * @extends {AbstractEvents} * @constructor + * @alias Blockly.Events.CommentBase */ const CommentBase = function(opt_comment) { /** diff --git a/core/events/events_comment_change.js b/core/events/events_comment_change.js index 7289d2779..57c72ff87 100644 --- a/core/events/events_comment_change.js +++ b/core/events/events_comment_change.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Class for comment change event. + * @namespace Blockly.Events.CommentChange + */ goog.module('Blockly.Events.CommentChange'); const CommentBase = goog.require('Blockly.Events.CommentBase'); @@ -28,6 +32,7 @@ const registry = goog.require('Blockly.registry'); * @param {string=} opt_newContents New contents of the comment. * @extends {CommentBase} * @constructor + * @alias Blockly.Events.CommentChange */ const CommentChange = function(opt_comment, opt_oldContents, opt_newContents) { CommentChange.superClass_.constructor.call(this, opt_comment); diff --git a/core/events/events_comment_create.js b/core/events/events_comment_create.js index 9964fc135..9bd4159ce 100644 --- a/core/events/events_comment_create.js +++ b/core/events/events_comment_create.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Class for comment creation event. + * @namespace Blockly.Events.CommentCreate + */ goog.module('Blockly.Events.CommentCreate'); const CommentBase = goog.require('Blockly.Events.CommentBase'); @@ -27,6 +31,7 @@ const registry = goog.require('Blockly.registry'); * Undefined for a blank event. * @extends {CommentBase} * @constructor + * @alias Blockly.Events.CommentCreate */ const CommentCreate = function(opt_comment) { CommentCreate.superClass_.constructor.call(this, opt_comment); diff --git a/core/events/events_comment_delete.js b/core/events/events_comment_delete.js index b33a154d7..03b6f3f62 100644 --- a/core/events/events_comment_delete.js +++ b/core/events/events_comment_delete.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Class for comment deletion event. + * @namespace Blockly.Events.CommentDelete + */ goog.module('Blockly.Events.CommentDelete'); const CommentBase = goog.require('Blockly.Events.CommentBase'); @@ -26,6 +30,7 @@ const registry = goog.require('Blockly.registry'); * Undefined for a blank event. * @extends {CommentBase} * @constructor + * @alias Blockly.Events.CommentDelete */ const CommentDelete = function(opt_comment) { CommentDelete.superClass_.constructor.call(this, opt_comment); diff --git a/core/events/events_comment_move.js b/core/events/events_comment_move.js index b2f53fea8..6ad249143 100644 --- a/core/events/events_comment_move.js +++ b/core/events/events_comment_move.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Class for comment move event. + * @namespace Blockly.Events.CommentMove + */ goog.module('Blockly.Events.CommentMove'); const CommentBase = goog.require('Blockly.Events.CommentBase'); @@ -27,6 +31,7 @@ const registry = goog.require('Blockly.registry'); * moved. Undefined for a blank event. * @extends {CommentBase} * @constructor + * @alias Blockly.Events.CommentMove */ const CommentMove = function(opt_comment) { CommentMove.superClass_.constructor.call(this, opt_comment); diff --git a/core/events/events_marker_move.js b/core/events/events_marker_move.js index 3d55f0d97..b8f041cf2 100644 --- a/core/events/events_marker_move.js +++ b/core/events/events_marker_move.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Events fired as a result of a marker move. + * @namespace Blockly.Events.MarkerMove + */ goog.module('Blockly.Events.MarkerMove'); const UiBase = goog.require('Blockly.Events.UiBase'); @@ -35,6 +39,7 @@ const {Block} = goog.requireType('Blockly.Block'); * Undefined for a blank event. * @extends {UiBase} * @constructor + * @alias Blockly.Events.MarkerMove */ const MarkerMove = function(opt_block, isCursor, opt_oldNode, opt_newNode) { let workspaceId = opt_block ? opt_block.workspace.id : undefined; diff --git a/core/events/events_selected.js b/core/events/events_selected.js index 12dba4891..315fb3899 100644 --- a/core/events/events_selected.js +++ b/core/events/events_selected.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Events fired as a result of element select action. + * @namespace Blockly.Events.Selected + */ goog.module('Blockly.Events.Selected'); const UiBase = goog.require('Blockly.Events.UiBase'); @@ -28,6 +32,7 @@ const registry = goog.require('Blockly.registry'); * Null if no element previously selected. Undefined for a blank event. * @extends {UiBase} * @constructor + * @alias Blockly.Events.Selected */ const Selected = function(opt_oldElementId, opt_newElementId, opt_workspaceId) { Selected.superClass_.constructor.call(this, opt_workspaceId); diff --git a/core/events/events_theme_change.js b/core/events/events_theme_change.js index 13e1f35fc..bf30d157a 100644 --- a/core/events/events_theme_change.js +++ b/core/events/events_theme_change.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Events fired as a result of a theme update. + * @namespace Blockly.Events.ThemeChange + */ goog.module('Blockly.Events.ThemeChange'); const UiBase = goog.require('Blockly.Events.UiBase'); @@ -25,6 +29,7 @@ const registry = goog.require('Blockly.registry'); * event. Undefined for a blank event. * @extends {UiBase} * @constructor + * @alias Blockly.Events.ThemeChange */ const ThemeChange = function(opt_themeName, opt_workspaceId) { ThemeChange.superClass_.constructor.call(this, opt_workspaceId); diff --git a/core/events/events_toolbox_item_select.js b/core/events/events_toolbox_item_select.js index 44d0a1594..1c6d7f0c1 100644 --- a/core/events/events_toolbox_item_select.js +++ b/core/events/events_toolbox_item_select.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Events fired as a result of selecting an item on the toolbox. + * @namespace Blockly.Events.ToolboxItemSelect + */ goog.module('Blockly.Events.ToolboxItemSelect'); const UiBase = goog.require('Blockly.Events.UiBase'); @@ -28,6 +32,7 @@ const registry = goog.require('Blockly.registry'); * Undefined for a blank event. * @extends {UiBase} * @constructor + * @alias Blockly.Events.ToolboxItemSelect */ const ToolboxItemSelect = function(opt_oldItem, opt_newItem, opt_workspaceId) { ToolboxItemSelect.superClass_.constructor.call(this, opt_workspaceId); diff --git a/core/events/events_trashcan_open.js b/core/events/events_trashcan_open.js index 1bb49dea8..ecfc9c4cb 100644 --- a/core/events/events_trashcan_open.js +++ b/core/events/events_trashcan_open.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Events fired as a result of trashcan flyout open and close. + * @namespace Blockly.Events.TrashcanOpen + */ goog.module('Blockly.Events.TrashcanOpen'); const UiBase = goog.require('Blockly.Events.UiBase'); @@ -26,6 +30,7 @@ const registry = goog.require('Blockly.registry'); * Undefined for a blank event. * @extends {UiBase} * @constructor + * @alias Blockly.Events.TrashcanOpen */ const TrashcanOpen = function(opt_isOpen, opt_workspaceId) { TrashcanOpen.superClass_.constructor.call(this, opt_workspaceId); diff --git a/core/events/events_ui.js b/core/events/events_ui.js index 44a743fef..e6e0a0c31 100644 --- a/core/events/events_ui.js +++ b/core/events/events_ui.js @@ -11,6 +11,11 @@ */ 'use strict'; +/** + * (Deprecated) Events fired as a result of UI actions in + * Blockly's editor. + * @namespace Blockly.Events.Ui + */ goog.module('Blockly.Events.Ui'); const UiBase = goog.require('Blockly.Events.UiBase'); @@ -32,6 +37,7 @@ const {Block} = goog.requireType('Blockly.Block'); * @extends {UiBase} * @deprecated December 2020. Instead use a more specific UI event. * @constructor + * @alias Blockly.Events.Ui */ const Ui = function(opt_block, opt_element, opt_oldValue, opt_newValue) { const workspaceId = opt_block ? opt_block.workspace.id : undefined; diff --git a/core/events/events_ui_base.js b/core/events/events_ui_base.js index f0204616e..b18c75800 100644 --- a/core/events/events_ui_base.js +++ b/core/events/events_ui_base.js @@ -11,6 +11,11 @@ */ 'use strict'; +/** + * Base class for events fired as a result of UI actions in + * Blockly's editor. + * @namespace Blockly.Events.UiBase + */ goog.module('Blockly.Events.UiBase'); const Abstract = goog.require('Blockly.Events.Abstract'); @@ -27,6 +32,7 @@ const object = goog.require('Blockly.utils.object'); * Undefined for a blank event. * @extends {Abstract} * @constructor + * @alias Blockly.Events.UiBase */ const UiBase = function(opt_workspaceId) { UiBase.superClass_.constructor.call(this); diff --git a/core/events/events_var_base.js b/core/events/events_var_base.js index 20710c73c..f26892b78 100644 --- a/core/events/events_var_base.js +++ b/core/events/events_var_base.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Abstract class for a variable event. + * @namespace Blockly.Events.VarBase + */ goog.module('Blockly.Events.VarBase'); const Abstract = goog.require('Blockly.Events.Abstract'); @@ -24,6 +28,7 @@ const object = goog.require('Blockly.utils.object'); * corresponds to. Undefined for a blank event. * @extends {Abstract} * @constructor + * @alias Blockly.Events.VarBase */ const VarBase = function(opt_variable) { VarBase.superClass_.constructor.call(this); diff --git a/core/events/events_var_create.js b/core/events/events_var_create.js index 00ba59cfe..8c7558f2d 100644 --- a/core/events/events_var_create.js +++ b/core/events/events_var_create.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Class for a variable creation event. + * @namespace Blockly.Events.VarCreate + */ goog.module('Blockly.Events.VarCreate'); const VarBase = goog.require('Blockly.Events.VarBase'); @@ -26,6 +30,7 @@ const registry = goog.require('Blockly.registry'); * for a blank event. * @extends {VarBase} * @constructor + * @alias Blockly.Events.VarCreate */ const VarCreate = function(opt_variable) { VarCreate.superClass_.constructor.call(this, opt_variable); diff --git a/core/events/events_var_delete.js b/core/events/events_var_delete.js index 32d5644aa..2540f0d10 100644 --- a/core/events/events_var_delete.js +++ b/core/events/events_var_delete.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Classes for all types of variable events. + * @namespace Blockly.Events.VarDelete + */ goog.module('Blockly.Events.VarDelete'); const VarBase = goog.require('Blockly.Events.VarBase'); @@ -26,6 +30,7 @@ const registry = goog.require('Blockly.registry'); * for a blank event. * @extends {VarBase} * @constructor + * @alias Blockly.Events.VarDelete */ const VarDelete = function(opt_variable) { VarDelete.superClass_.constructor.call(this, opt_variable); diff --git a/core/events/events_var_rename.js b/core/events/events_var_rename.js index f7c9f8890..f9f4e59f9 100644 --- a/core/events/events_var_rename.js +++ b/core/events/events_var_rename.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Class for a variable rename event. + * @namespace Blockly.Events.VarRename + */ goog.module('Blockly.Events.VarRename'); const VarBase = goog.require('Blockly.Events.VarBase'); @@ -27,6 +31,7 @@ const registry = goog.require('Blockly.registry'); * @param {string=} newName The new name the variable will be changed to. * @extends {VarBase} * @constructor + * @alias Blockly.Events.VarRename */ const VarRename = function(opt_variable, newName) { VarRename.superClass_.constructor.call(this, opt_variable); diff --git a/core/events/events_viewport.js b/core/events/events_viewport.js index 6eccd0a85..b02688db2 100644 --- a/core/events/events_viewport.js +++ b/core/events/events_viewport.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Events fired as a result of a viewport change. + * @namespace Blockly.Events.ViewportChange + */ goog.module('Blockly.Events.ViewportChange'); const UiBase = goog.require('Blockly.Events.UiBase'); @@ -32,6 +36,7 @@ const registry = goog.require('Blockly.registry'); * blank event. * @extends {UiBase} * @constructor + * @alias Blockly.Events.ViewportChange */ const ViewportChange = function( opt_top, opt_left, opt_scale, opt_workspaceId, opt_oldScale) { diff --git a/core/events/utils.js b/core/events/utils.js index 18a42f060..355fdac80 100644 --- a/core/events/utils.js +++ b/core/events/utils.js @@ -10,6 +10,11 @@ */ 'use strict'; +/** + * Helper methods for events that are fired as a result of + * actions in Blockly's editor. + * @namespace Blockly.Events.utils + */ goog.module('Blockly.Events.utils'); /* eslint-disable-next-line no-unused-vars */ @@ -44,7 +49,7 @@ let recordUndo = true; /** * Sets whether events should be added to the undo stack. * @param {boolean} newValue True if events should be added to the undo stack. - * @alias Blockly.Events.setRecordUndo + * @alias Blockly.Events.utils.setRecordUndo */ const setRecordUndo = function(newValue) { recordUndo = newValue; @@ -54,7 +59,7 @@ exports.setRecordUndo = setRecordUndo; /** * Returns whether or not events will be added to the undo stack. * @returns {boolean} True if events will be added to the undo stack. - * @alias Blockly.Events.getRecordUndo + * @alias Blockly.Events.utils.getRecordUndo */ const getRecordUndo = function() { return recordUndo; @@ -70,7 +75,7 @@ let disabled = 0; /** * Name of event that creates a block. Will be deprecated for BLOCK_CREATE. * @const - * @alias Blockly.Events.CREATE + * @alias Blockly.Events.utils.CREATE */ const CREATE = 'create'; exports.CREATE = CREATE; @@ -78,7 +83,7 @@ exports.CREATE = CREATE; /** * Name of event that creates a block. * @const - * @alias Blockly.Events.BLOCK_CREATE + * @alias Blockly.Events.utils.BLOCK_CREATE */ const BLOCK_CREATE = CREATE; exports.BLOCK_CREATE = BLOCK_CREATE; @@ -86,7 +91,7 @@ exports.BLOCK_CREATE = BLOCK_CREATE; /** * Name of event that deletes a block. Will be deprecated for BLOCK_DELETE. * @const - * @alias Blockly.Events.DELETE + * @alias Blockly.Events.utils.DELETE */ const DELETE = 'delete'; exports.DELETE = DELETE; @@ -94,7 +99,7 @@ exports.DELETE = DELETE; /** * Name of event that deletes a block. * @const - * @alias Blockly.Events.BLOCK_DELETE + * @alias Blockly.Events.utils.BLOCK_DELETE */ const BLOCK_DELETE = DELETE; exports.BLOCK_DELETE = BLOCK_DELETE; @@ -102,7 +107,7 @@ exports.BLOCK_DELETE = BLOCK_DELETE; /** * Name of event that changes a block. Will be deprecated for BLOCK_CHANGE. * @const - * @alias Blockly.Events.CHANGE + * @alias Blockly.Events.utils.CHANGE */ const CHANGE = 'change'; exports.CHANGE = CHANGE; @@ -110,7 +115,7 @@ exports.CHANGE = CHANGE; /** * Name of event that changes a block. * @const - * @alias Blockly.Events.BLOCK_CHANGE + * @alias Blockly.Events.utils.BLOCK_CHANGE */ const BLOCK_CHANGE = CHANGE; exports.BLOCK_CHANGE = BLOCK_CHANGE; @@ -118,7 +123,7 @@ exports.BLOCK_CHANGE = BLOCK_CHANGE; /** * Name of event that moves a block. Will be deprecated for BLOCK_MOVE. * @const - * @alias Blockly.Events.MOVE + * @alias Blockly.Events.utils.MOVE */ const MOVE = 'move'; exports.MOVE = MOVE; @@ -126,7 +131,7 @@ exports.MOVE = MOVE; /** * Name of event that moves a block. * @const - * @alias Blockly.Events.BLOCK_MOVE + * @alias Blockly.Events.utils.BLOCK_MOVE */ const BLOCK_MOVE = MOVE; exports.BLOCK_MOVE = BLOCK_MOVE; @@ -134,7 +139,7 @@ exports.BLOCK_MOVE = BLOCK_MOVE; /** * Name of event that creates a variable. * @const - * @alias Blockly.Events.VAR_CREATE + * @alias Blockly.Events.utils.VAR_CREATE */ const VAR_CREATE = 'var_create'; exports.VAR_CREATE = VAR_CREATE; @@ -142,7 +147,7 @@ exports.VAR_CREATE = VAR_CREATE; /** * Name of event that deletes a variable. * @const - * @alias Blockly.Events.VAR_DELETE + * @alias Blockly.Events.utils.VAR_DELETE */ const VAR_DELETE = 'var_delete'; exports.VAR_DELETE = VAR_DELETE; @@ -150,7 +155,7 @@ exports.VAR_DELETE = VAR_DELETE; /** * Name of event that renames a variable. * @const - * @alias Blockly.Events.VAR_RENAME + * @alias Blockly.Events.utils.VAR_RENAME */ const VAR_RENAME = 'var_rename'; exports.VAR_RENAME = VAR_RENAME; @@ -158,7 +163,7 @@ exports.VAR_RENAME = VAR_RENAME; /** * Name of generic event that records a UI change. * @const - * @alias Blockly.Events.UI + * @alias Blockly.Events.utils.UI */ const UI = 'ui'; exports.UI = UI; @@ -166,7 +171,7 @@ exports.UI = UI; /** * Name of event that record a block drags a block. * @const - * @alias Blockly.Events.BLOCK_DRAG + * @alias Blockly.Events.utils.BLOCK_DRAG */ const BLOCK_DRAG = 'drag'; exports.BLOCK_DRAG = BLOCK_DRAG; @@ -174,7 +179,7 @@ exports.BLOCK_DRAG = BLOCK_DRAG; /** * Name of event that records a change in selected element. * @const - * @alias Blockly.Events.SELECTED + * @alias Blockly.Events.utils.SELECTED */ const SELECTED = 'selected'; exports.SELECTED = SELECTED; @@ -182,7 +187,7 @@ exports.SELECTED = SELECTED; /** * Name of event that records a click. * @const - * @alias Blockly.Events.CLICK + * @alias Blockly.Events.utils.CLICK */ const CLICK = 'click'; exports.CLICK = CLICK; @@ -190,7 +195,7 @@ exports.CLICK = CLICK; /** * Name of event that records a marker move. * @const - * @alias Blockly.Events.MARKER_MOVE + * @alias Blockly.Events.utils.MARKER_MOVE */ const MARKER_MOVE = 'marker_move'; exports.MARKER_MOVE = MARKER_MOVE; @@ -198,7 +203,7 @@ exports.MARKER_MOVE = MARKER_MOVE; /** * Name of event that records a bubble open. * @const - * @alias Blockly.Events.BUBBLE_OPEN + * @alias Blockly.Events.utils.BUBBLE_OPEN */ const BUBBLE_OPEN = 'bubble_open'; exports.BUBBLE_OPEN = BUBBLE_OPEN; @@ -206,7 +211,7 @@ exports.BUBBLE_OPEN = BUBBLE_OPEN; /** * Name of event that records a trashcan open. * @const - * @alias Blockly.Events.TRASHCAN_OPEN + * @alias Blockly.Events.utils.TRASHCAN_OPEN */ const TRASHCAN_OPEN = 'trashcan_open'; exports.TRASHCAN_OPEN = TRASHCAN_OPEN; @@ -214,7 +219,7 @@ exports.TRASHCAN_OPEN = TRASHCAN_OPEN; /** * Name of event that records a toolbox item select. * @const - * @alias Blockly.Events.TOOLBOX_ITEM_SELECT + * @alias Blockly.Events.utils.TOOLBOX_ITEM_SELECT */ const TOOLBOX_ITEM_SELECT = 'toolbox_item_select'; exports.TOOLBOX_ITEM_SELECT = TOOLBOX_ITEM_SELECT; @@ -222,7 +227,7 @@ exports.TOOLBOX_ITEM_SELECT = TOOLBOX_ITEM_SELECT; /** * Name of event that records a theme change. * @const - * @alias Blockly.Events.THEME_CHANGE + * @alias Blockly.Events.utils.THEME_CHANGE */ const THEME_CHANGE = 'theme_change'; exports.THEME_CHANGE = THEME_CHANGE; @@ -230,7 +235,7 @@ exports.THEME_CHANGE = THEME_CHANGE; /** * Name of event that records a viewport change. * @const - * @alias Blockly.Events.VIEWPORT_CHANGE + * @alias Blockly.Events.utils.VIEWPORT_CHANGE */ const VIEWPORT_CHANGE = 'viewport_change'; exports.VIEWPORT_CHANGE = VIEWPORT_CHANGE; @@ -238,7 +243,7 @@ exports.VIEWPORT_CHANGE = VIEWPORT_CHANGE; /** * Name of event that creates a comment. * @const - * @alias Blockly.Events.COMMENT_CREATE + * @alias Blockly.Events.utils.COMMENT_CREATE */ const COMMENT_CREATE = 'comment_create'; exports.COMMENT_CREATE = COMMENT_CREATE; @@ -246,7 +251,7 @@ exports.COMMENT_CREATE = COMMENT_CREATE; /** * Name of event that deletes a comment. * @const - * @alias Blockly.Events.COMMENT_DELETE + * @alias Blockly.Events.utils.COMMENT_DELETE */ const COMMENT_DELETE = 'comment_delete'; exports.COMMENT_DELETE = COMMENT_DELETE; @@ -254,7 +259,7 @@ exports.COMMENT_DELETE = COMMENT_DELETE; /** * Name of event that changes a comment. * @const - * @alias Blockly.Events.COMMENT_CHANGE + * @alias Blockly.Events.utils.COMMENT_CHANGE */ const COMMENT_CHANGE = 'comment_change'; exports.COMMENT_CHANGE = COMMENT_CHANGE; @@ -262,14 +267,14 @@ exports.COMMENT_CHANGE = COMMENT_CHANGE; /** * Name of event that moves a comment. * @const - * @alias Blockly.Events.COMMENT_MOVE + * @alias Blockly.Events.utils.COMMENT_MOVE */ const COMMENT_MOVE = 'comment_move'; exports.COMMENT_MOVE = COMMENT_MOVE; /** * Name of event that records a workspace load. - * @alias Blockly.Events.FINISHED_LOADING + * @alias Blockly.Events.utils.FINISHED_LOADING */ const FINISHED_LOADING = 'finished_loading'; exports.FINISHED_LOADING = FINISHED_LOADING; @@ -282,7 +287,7 @@ exports.FINISHED_LOADING = FINISHED_LOADING; * appear connected. * @typedef {!BlockCreate|!BlockMove| * !CommentCreate|!CommentMove} - * @alias Blockly.Events.BumpEvent + * @alias Blockly.Events.utils.BumpEvent */ let BumpEvent; exports.BumpEvent = BumpEvent; @@ -294,7 +299,7 @@ exports.BumpEvent = BumpEvent; * Not to be confused with bumping so that disconnected connections do not * appear connected. * @const - * @alias Blockly.Events.BUMP_EVENTS + * @alias Blockly.Events.utils.BUMP_EVENTS */ const BUMP_EVENTS = [BLOCK_CREATE, BLOCK_MOVE, COMMENT_CREATE, COMMENT_MOVE]; exports.BUMP_EVENTS = BUMP_EVENTS; @@ -307,7 +312,7 @@ const FIRE_QUEUE = []; /** * Create a custom event and fire it. * @param {!Abstract} event Custom data for event. - * @alias Blockly.Events.fire + * @alias Blockly.Events.utils.fire */ const fire = function(event) { if (!isEnabled()) { @@ -344,7 +349,7 @@ const fireNow = function() { * @param {!Array} queueIn Array of events. * @param {boolean} forward True if forward (redo), false if backward (undo). * @return {!Array} Array of filtered events. - * @alias Blockly.Events.filter + * @alias Blockly.Events.utils.filter */ const filter = function(queueIn, forward) { let queue = queueIn.slice(); // Shallow copy of queue. @@ -418,7 +423,7 @@ exports.filter = filter; /** * 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.clearPendingUndo + * @alias Blockly.Events.utils.clearPendingUndo */ const clearPendingUndo = function() { for (let i = 0, event; (event = FIRE_QUEUE[i]); i++) { @@ -429,7 +434,7 @@ exports.clearPendingUndo = clearPendingUndo; /** * Stop sending events. Every call to this function MUST also call enable. - * @alias Blockly.Events.disable + * @alias Blockly.Events.utils.disable */ const disable = function() { disabled++; @@ -439,7 +444,7 @@ exports.disable = disable; /** * Start sending events. Unless events were already disabled when the * corresponding call to disable was made. - * @alias Blockly.Events.enable + * @alias Blockly.Events.utils.enable */ const enable = function() { disabled--; @@ -449,7 +454,7 @@ exports.enable = enable; /** * Returns whether events may be fired or not. * @return {boolean} True if enabled. - * @alias Blockly.Events.isEnabled + * @alias Blockly.Events.utils.isEnabled */ const isEnabled = function() { return disabled == 0; @@ -459,7 +464,7 @@ exports.isEnabled = isEnabled; /** * Current group. * @return {string} ID string. - * @alias Blockly.Events.getGroup + * @alias Blockly.Events.utils.getGroup */ const getGroup = function() { return group; @@ -470,7 +475,7 @@ exports.getGroup = getGroup; * Start or stop a group. * @param {boolean|string} state True to start new group, false to end group. * String to set group explicitly. - * @alias Blockly.Events.setGroup + * @alias Blockly.Events.utils.setGroup */ const setGroup = function(state) { if (typeof state == 'boolean') { @@ -485,7 +490,7 @@ exports.setGroup = setGroup; * Compute a list of the IDs of the specified block and all its descendants. * @param {!Block} block The root block. * @return {!Array} List of block IDs. - * @alias Blockly.Events.getDescendantIds + * @alias Blockly.Events.utils.getDescendantIds */ const getDescendantIds = function(block) { const ids = []; @@ -504,7 +509,7 @@ exports.getDescendantIds = getDescendantIds; * @param {!Workspace} workspace Target workspace for event. * @return {!Abstract} The event represented by the JSON. * @throws {Error} if an event type is not found in the registry. - * @alias Blockly.Events.fromJson + * @alias Blockly.Events.utils.fromJson */ const fromJson = function(json, workspace) { const eventClass = get(json.type); @@ -523,7 +528,7 @@ exports.fromJson = fromJson; * @param {string} eventType The type of the event to get. * @return {?function(new:Abstract, ...?)} The event class with * the given type or null if none exists. - * @alias Blockly.Events.get + * @alias Blockly.Events.utils.get */ const get = function(eventType) { return registry.getClass(registry.Type.EVENT, eventType); @@ -536,7 +541,7 @@ exports.get = get; * Recommend setting the 'disable' option to 'false' in the config so that * users don't try to re-enable disabled orphan blocks. * @param {!Abstract} event Custom data for event. - * @alias Blockly.Events.disableOrphans + * @alias Blockly.Events.utils.disableOrphans */ const disableOrphans = function(event) { if (event.type == MOVE || event.type == CREATE) { diff --git a/core/events/workspace_events.js b/core/events/workspace_events.js index 61351375b..f1f43abeb 100644 --- a/core/events/workspace_events.js +++ b/core/events/workspace_events.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Class for a finished loading workspace event. + * @namespace Blockly.Events.FinishedLoading + */ goog.module('Blockly.Events.FinishedLoading'); const Abstract = goog.require('Blockly.Events.Abstract'); @@ -29,6 +33,7 @@ const registry = goog.require('Blockly.registry'); * loading. Undefined for a blank event. * @extends {Abstract} * @constructor + * @alias Blockly.Events.FinishedLoading */ const FinishedLoading = function(opt_workspace) { /** diff --git a/core/extensions.js b/core/extensions.js index 876169ff0..426de3f6b 100644 --- a/core/extensions.js +++ b/core/extensions.js @@ -14,8 +14,11 @@ 'use strict'; /** - * @name Blockly.Extensions - * @namespace + * Extensions are functions that help initialize blocks, usually + * adding dynamic behavior such as onchange handlers and mutators. These + * are applied using Block.applyExtension(), or the JSON "extensions" + * array attribute. + * @namespace Blockly.Extensions */ goog.module('Blockly.Extensions'); diff --git a/core/field.js b/core/field.js index be6318797..8f14cce0b 100644 --- a/core/field.js +++ b/core/field.js @@ -12,6 +12,12 @@ */ 'use strict'; +/** + * Field. Used for editable titles, variables, etc. + * This is an abstract class that defines the UI on the block. Actual + * instances would be FieldTextInput, FieldDropdown, etc. + * @namespace Blockly.Field + */ goog.module('Blockly.Field'); /* eslint-disable-next-line no-unused-vars */ @@ -72,6 +78,7 @@ goog.require('Blockly.Gesture'); * @implements {IASTNodeLocationWithBlock} * @implements {IKeyboardAccessible} * @implements {IRegistrable} + * @alias Blockly.Field */ const Field = function(value, opt_validator, opt_config) { /** diff --git a/core/field_angle.js b/core/field_angle.js index 657adfd6d..6b1ade13f 100644 --- a/core/field_angle.js +++ b/core/field_angle.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Angle input field. + * @namespace Blockly.FieldAngle + */ goog.module('Blockly.FieldAngle'); const Css = goog.require('Blockly.Css'); @@ -38,6 +42,7 @@ const userAgent = goog.require('Blockly.utils.userAgent'); * for a list of properties this parameter supports. * @extends {FieldTextInput} * @constructor + * @alias Blockly.FieldAngle */ const FieldAngle = function(opt_value, opt_validator, opt_config) { diff --git a/core/field_checkbox.js b/core/field_checkbox.js index cb4145d9f..62330800d 100644 --- a/core/field_checkbox.js +++ b/core/field_checkbox.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Checkbox field. Checked or not checked. + * @namespace Blockly.FieldCheckbox + */ goog.module('Blockly.FieldCheckbox'); const Field = goog.require('Blockly.Field'); @@ -34,6 +38,7 @@ goog.require('Blockly.Events.BlockChange'); * for a list of properties this parameter supports. * @extends {Field} * @constructor + * @alias Blockly.FieldCheckbox */ const FieldCheckbox = function(opt_value, opt_validator, opt_config) { /** diff --git a/core/field_colour.js b/core/field_colour.js index 0961d54b4..3aef42c75 100644 --- a/core/field_colour.js +++ b/core/field_colour.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Colour input field. + * @namespace Blockly.FieldColour + */ goog.module('Blockly.FieldColour'); const Css = goog.require('Blockly.Css'); @@ -42,6 +46,7 @@ goog.require('Blockly.Events.BlockChange'); * for a list of properties this parameter supports. * @extends {Field} * @constructor + * @alias Blockly.FieldColour */ const FieldColour = function(opt_value, opt_validator, opt_config) { FieldColour.superClass_.constructor.call( diff --git a/core/field_dropdown.js b/core/field_dropdown.js index e2d390f5f..d80a581f5 100644 --- a/core/field_dropdown.js +++ b/core/field_dropdown.js @@ -12,6 +12,12 @@ */ 'use strict'; +/** + * Dropdown input field. Used for editable titles and variables. + * In the interests of a consistent UI, the toolbox shares some functions and + * properties with the context menu. + * @namespace Blockly.FieldDropdown + */ goog.module('Blockly.FieldDropdown'); const Coordinate = goog.require('Blockly.utils.Coordinate'); @@ -44,6 +50,7 @@ const utilsString = goog.require('Blockly.utils.string'); * @extends {Field} * @constructor * @throws {TypeError} If `menuGenerator` options are incorrectly structured. + * @alias Blockly.FieldDropdown */ const FieldDropdown = function(menuGenerator, opt_validator, opt_config) { if (typeof menuGenerator != 'function') { diff --git a/core/field_image.js b/core/field_image.js index 9df6754ff..8e71d1548 100644 --- a/core/field_image.js +++ b/core/field_image.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Image field. Used for pictures, icons, etc. + * @namespace Blockly.FieldImage + */ goog.module('Blockly.FieldImage'); const Field = goog.require('Blockly.Field'); @@ -37,6 +41,7 @@ const utils = goog.require('Blockly.utils'); * for a list of properties this parameter supports. * @extends {Field} * @constructor + * @alias Blockly.FieldImage */ const FieldImage = function( src, width, height, opt_alt, opt_onClick, opt_flipRtl, opt_config) { diff --git a/core/field_label.js b/core/field_label.js index 2f2e78e3a..dc798f8e3 100644 --- a/core/field_label.js +++ b/core/field_label.js @@ -11,6 +11,11 @@ */ 'use strict'; +/** + * Non-editable, non-serializable text field. Used for titles, + * labels, etc. + * @namespace Blockly.FieldLabel + */ goog.module('Blockly.FieldLabel'); const Field = goog.require('Blockly.Field'); @@ -31,6 +36,7 @@ const utils = goog.require('Blockly.utils'); * for a list of properties this parameter supports. * @extends {Field} * @constructor + * @alias Blockly.FieldLabel */ const FieldLabel = function(opt_value, opt_class, opt_config) { /** diff --git a/core/field_label_serializable.js b/core/field_label_serializable.js index e8f467f69..ff42f3887 100644 --- a/core/field_label_serializable.js +++ b/core/field_label_serializable.js @@ -11,6 +11,12 @@ */ 'use strict'; +/** + * Non-editable, serializable text field. Behaves like a + * normal label but is serialized to XML. It may only be + * edited programmatically. + * @namespace Blockly.FieldLabelSerializable + */ goog.module('Blockly.FieldLabelSerializable'); const FieldLabel = goog.require('Blockly.FieldLabel'); @@ -31,6 +37,7 @@ const utils = goog.require('Blockly.utils'); * @extends {FieldLabel} * @constructor * + * @alias Blockly.FieldLabelSerializable */ const FieldLabelSerializable = function(opt_value, opt_class, opt_config) { FieldLabelSerializable.superClass_.constructor.call( diff --git a/core/field_multilineinput.js b/core/field_multilineinput.js index a2776d294..04d98dad4 100644 --- a/core/field_multilineinput.js +++ b/core/field_multilineinput.js @@ -12,6 +12,10 @@ */ 'use strict'; +/** + * Text Area field. + * @namespace Blockly.FieldMultilineInput + */ goog.module('Blockly.FieldMultilineInput'); const Css = goog.require('Blockly.Css'); @@ -42,6 +46,7 @@ const utils = goog.require('Blockly.utils'); * for a list of properties this parameter supports. * @extends {FieldTextInput} * @constructor + * @alias Blockly.FieldMultilineInput */ const FieldMultilineInput = function(opt_value, opt_validator, opt_config) { FieldMultilineInput.superClass_.constructor.call( diff --git a/core/field_number.js b/core/field_number.js index 848e397c9..c052340dd 100644 --- a/core/field_number.js +++ b/core/field_number.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Number input field + * @namespace Blockly.FieldNumber + */ goog.module('Blockly.FieldNumber'); const FieldTextInput = goog.require('Blockly.FieldTextInput'); @@ -34,6 +38,7 @@ const object = goog.require('Blockly.utils.object'); * for a list of properties this parameter supports. * @extends {FieldTextInput} * @constructor + * @alias Blockly.FieldNumber */ const FieldNumber = function( opt_value, opt_min, opt_max, opt_precision, opt_validator, opt_config) { diff --git a/core/field_registry.js b/core/field_registry.js index 2d2cdf73f..eb920e5b5 100644 --- a/core/field_registry.js +++ b/core/field_registry.js @@ -12,6 +12,12 @@ */ 'use strict'; +/** + * Fields can be created based on a JSON definition. This file + * contains methods for registering those JSON definitions, and building the + * fields based on JSON. + * @namespace Blockly.fieldRegistry + */ goog.module('Blockly.fieldRegistry'); /* eslint-disable-next-line no-unused-vars */ @@ -31,6 +37,7 @@ const registry = goog.require('Blockly.registry'); * @throws {Error} if the type name is empty, the field is already * registered, or the fieldClass is not an object containing a fromJson * function. + * @alias Blockly.fieldRegistry.register */ const register = function(type, fieldClass) { registry.register(registry.Type.FIELD, type, fieldClass); @@ -40,6 +47,7 @@ exports.register = register; /** * Unregisters the field registered with the given type. * @param {string} type The field type name as used in the JSON definition. + * @alias Blockly.fieldRegistry.unregister */ const unregister = function(type) { registry.unregister(registry.Type.FIELD, type); @@ -54,6 +62,7 @@ exports.unregister = unregister; * to the field type. * @return {?Field} The new field instance or null if a field wasn't * found with the given type name + * @alias Blockly.fieldRegistry.fromJson */ const fromJson = function(options) { const fieldObject = /** @type {?IRegistrableField} */ ( diff --git a/core/field_textinput.js b/core/field_textinput.js index 706ddec94..4997790b8 100644 --- a/core/field_textinput.js +++ b/core/field_textinput.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Text input field. + * @namespace Blockly.FieldTextInput + */ goog.module('Blockly.FieldTextInput'); const Coordinate = goog.require('Blockly.utils.Coordinate'); @@ -48,6 +52,7 @@ goog.require('Blockly.Events.BlockChange'); * for a list of properties this parameter supports. * @extends {Field} * @constructor + * @alias Blockly.FieldTextInput */ const FieldTextInput = function(opt_value, opt_validator, opt_config) { /** diff --git a/core/field_variable.js b/core/field_variable.js index c4de96edc..6348a1a49 100644 --- a/core/field_variable.js +++ b/core/field_variable.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Variable input field. + * @namespace Blockly.FieldVariable + */ goog.module('Blockly.FieldVariable'); const FieldDropdown = goog.require('Blockly.FieldDropdown'); @@ -49,6 +53,7 @@ goog.require('Blockly.Events.BlockChange'); * for a list of properties this parameter supports. * @extends {FieldDropdown} * @constructor + * @alias Blockly.FieldVariable */ const FieldVariable = function( varName, opt_validator, opt_variableTypes, opt_defaultType, opt_config) { diff --git a/core/flyout_base.js b/core/flyout_base.js index f16e2877a..5a2268395 100644 --- a/core/flyout_base.js +++ b/core/flyout_base.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Flyout tray containing blocks which may be created. + * @namespace Blockly.Flyout + */ goog.module('Blockly.Flyout'); const ComponentManager = goog.require('Blockly.ComponentManager'); @@ -60,6 +64,7 @@ goog.require('Blockly.Touch'); * @abstract * @implements {IFlyout} * @extends {DeleteArea} + * @alias Blockly.Flyout */ const Flyout = function(workspaceOptions) { Flyout.superClass_.constructor.call(this); diff --git a/core/flyout_button.js b/core/flyout_button.js index 50f101f5a..345950318 100644 --- a/core/flyout_button.js +++ b/core/flyout_button.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Class for a button in the flyout. + * @namespace Blockly.FlyoutButton + */ goog.module('Blockly.FlyoutButton'); const Coordinate = goog.require('Blockly.utils.Coordinate'); @@ -35,6 +39,7 @@ const utils = goog.require('Blockly.utils'); * @param {boolean} isLabel Whether this button should be styled as a label. * @constructor * @package + * @alias Blockly.FlyoutButton */ const FlyoutButton = function(workspace, targetWorkspace, json, isLabel) { // Labels behave the same as buttons, but are styled differently. diff --git a/core/flyout_horizontal.js b/core/flyout_horizontal.js index 877b13840..4c7dc8800 100644 --- a/core/flyout_horizontal.js +++ b/core/flyout_horizontal.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Horizontal flyout tray containing blocks which may be created. + * @namespace Blockly.HorizontalFlyout + */ goog.module('Blockly.HorizontalFlyout'); /* eslint-disable-next-line no-unused-vars */ @@ -33,6 +37,7 @@ const toolbox = goog.require('Blockly.utils.toolbox'); * workspace. * @extends {Flyout} * @constructor + * @alias Blockly.HorizontalFlyout */ const HorizontalFlyout = function(workspaceOptions) { HorizontalFlyout.superClass_.constructor.call(this, workspaceOptions); diff --git a/core/flyout_metrics_manager.js b/core/flyout_metrics_manager.js index dde699902..6a56a10f1 100644 --- a/core/flyout_metrics_manager.js +++ b/core/flyout_metrics_manager.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Calculates and reports flyout workspace metrics. + * @namespace Blockly.FlyoutMetricsManager + */ goog.module('Blockly.FlyoutMetricsManager'); /* eslint-disable-next-line no-unused-vars */ @@ -27,6 +31,7 @@ const object = goog.require('Blockly.utils.object'); * @param {!IFlyout} flyout The flyout. * @extends {MetricsManager} * @constructor + * @alias Blockly.FlyoutMetricsManager */ const FlyoutMetricsManager = function(workspace, flyout) { /** diff --git a/core/flyout_vertical.js b/core/flyout_vertical.js index b201ebeac..92f1c686a 100644 --- a/core/flyout_vertical.js +++ b/core/flyout_vertical.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Layout code for a vertical variant of the flyout. + * @namespace Blockly.VerticalFlyout + */ goog.module('Blockly.VerticalFlyout'); /* eslint-disable-next-line no-unused-vars */ @@ -37,6 +41,7 @@ goog.require('Blockly.constants'); * workspace. * @extends {Flyout} * @constructor + * @alias Blockly.VerticalFlyout */ const VerticalFlyout = function(workspaceOptions) { VerticalFlyout.superClass_.constructor.call(this, workspaceOptions); diff --git a/core/generator.js b/core/generator.js index d121bb186..376ace2f8 100644 --- a/core/generator.js +++ b/core/generator.js @@ -11,6 +11,11 @@ */ 'use strict'; +/** + * Utility functions for generating executable code from + * Blockly code. + * @namespace Blockly.Generator + */ goog.module('Blockly.Generator'); /* eslint-disable-next-line no-unused-vars */ @@ -28,6 +33,7 @@ const {Block} = goog.requireType('Blockly.Block'); * Class for a code generator that translates the blocks into a language. * @param {string} name Language name of this generator. * @constructor + * @alias Blockly.Generator */ const Generator = function(name) { this.name_ = name; diff --git a/core/gesture.js b/core/gesture.js index 425773140..5a7444737 100644 --- a/core/gesture.js +++ b/core/gesture.js @@ -11,6 +11,11 @@ */ 'use strict'; +/** + * The class representing an in-progress gesture, usually a drag + * or a tap. + * @namespace Blockly.Gesture + */ goog.module('Blockly.Gesture'); const BubbleDragger = goog.require('Blockly.BubbleDragger'); @@ -55,6 +60,7 @@ goog.require('Blockly.Events.Click'); * @param {!WorkspaceSvg} creatorWorkspace The workspace that created * this gesture and has a reference to it. * @constructor + * @alias Blockly.Gesture */ const Gesture = function(e, creatorWorkspace) { /** diff --git a/core/grid.js b/core/grid.js index 9865364a2..894fdac25 100644 --- a/core/grid.js +++ b/core/grid.js @@ -11,6 +11,11 @@ */ 'use strict'; +/** + * Object for configuring and updating a workspace grid in + * Blockly. + * @namespace Blockly.Grid + */ goog.module('Blockly.Grid'); const Svg = goog.require('Blockly.utils.Svg'); @@ -26,6 +31,7 @@ const userAgent = goog.require('Blockly.utils.userAgent'); * See grid documentation: * https://developers.google.com/blockly/guides/configure/web/grid * @constructor + * @alias Blockly.Grid */ const Grid = function(pattern, options) { /** diff --git a/core/icon.js b/core/icon.js index 3fd8ccaf0..ae87330b0 100644 --- a/core/icon.js +++ b/core/icon.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Object representing an icon on a block. + * @namespace Blockly.Icon + */ goog.module('Blockly.Icon'); /* eslint-disable-next-line no-unused-vars */ @@ -29,6 +33,7 @@ const {BlockSvg} = goog.requireType('Blockly.BlockSvg'); * @param {BlockSvg} block The block associated with this icon. * @constructor * @abstract + * @alias Blockly.Icon */ const Icon = function(block) { /** diff --git a/core/inject.js b/core/inject.js index 4fedf8527..a50b503bc 100644 --- a/core/inject.js +++ b/core/inject.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Functions for injecting Blockly into a web page. + * @namespace Blockly.inject + */ goog.module('Blockly.inject'); /* eslint-disable-next-line no-unused-vars */ @@ -43,6 +47,7 @@ const {BlockDragSurfaceSvg} = goog.require('Blockly.BlockDragSurfaceSvg'); * or a CSS selector. * @param {BlocklyOptions=} opt_options Optional dictionary of options. * @return {!WorkspaceSvg} Newly created main workspace. + * @alias Blockly.inject */ const inject = function(container, opt_options) { if (typeof container == 'string') { diff --git a/core/input.js b/core/input.js index 5d503ff04..ef416a444 100644 --- a/core/input.js +++ b/core/input.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Object representing an input (value, statement, or dummy). + * @namespace Blockly.Input + */ goog.module('Blockly.Input'); /* eslint-disable-next-line no-unused-vars */ @@ -36,6 +40,7 @@ goog.require('Blockly.FieldLabel'); * @param {!Block} block The block containing this input. * @param {Connection} connection Optional connection for this input. * @constructor + * @alias Blockly.Input */ const Input = function(type, name, block, connection) { if (type != inputTypes.DUMMY && !name) { diff --git a/core/input_types.js b/core/input_types.js index b0af4ef87..858f0c2f3 100644 --- a/core/input_types.js +++ b/core/input_types.js @@ -11,6 +11,10 @@ 'use strict'; +/** + * An enum for the possible types of inputs. + * @namespace Blockly.inputTypes + */ goog.module('Blockly.inputTypes'); const {ConnectionType} = goog.require('Blockly.ConnectionType'); @@ -19,6 +23,7 @@ const {ConnectionType} = goog.require('Blockly.ConnectionType'); /** * Enum for the type of a connection or input. * @enum {number} + * @alias Blockly.inputTypes */ const inputTypes = { // A right-facing value input. E.g. 'set item to' or 'return'. diff --git a/core/insertion_marker_manager.js b/core/insertion_marker_manager.js index 1012bd867..ec1d1dcb8 100644 --- a/core/insertion_marker_manager.js +++ b/core/insertion_marker_manager.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Class that controls updates to connections during drags. + * @namespace Blockly.InsertionMarkerManager + */ goog.module('Blockly.InsertionMarkerManager'); const ComponentManager = goog.require('Blockly.ComponentManager'); @@ -39,6 +43,7 @@ const {ConnectionType} = goog.require('Blockly.ConnectionType'); * unhiglighting it as needed during a drag. * @param {!BlockSvg} block The top block in the stack being dragged. * @constructor + * @alias Blockly.InsertionMarkerManager */ const InsertionMarkerManager = function(block) { common.setSelected(block); diff --git a/core/interfaces/i_ast_node_location.js b/core/interfaces/i_ast_node_location.js index ddf987c5d..5a029fa24 100644 --- a/core/interfaces/i_ast_node_location.js +++ b/core/interfaces/i_ast_node_location.js @@ -11,11 +11,16 @@ 'use strict'; +/** + * The interface for an AST node location. + * @namespace Blockly.IASTNodeLocation + */ goog.module('Blockly.IASTNodeLocation'); /** * An AST node location interface. * @interface + * @alias Blockly.IASTNodeLocation */ const IASTNodeLocation = function() {}; diff --git a/core/interfaces/i_ast_node_location_svg.js b/core/interfaces/i_ast_node_location_svg.js index ffa67e6e0..0ac7eb0a9 100644 --- a/core/interfaces/i_ast_node_location_svg.js +++ b/core/interfaces/i_ast_node_location_svg.js @@ -11,6 +11,10 @@ 'use strict'; +/** + * The interface for an AST node location SVG. + * @namespace Blockly.IASTNodeLocationSvg + */ goog.module('Blockly.IASTNodeLocationSvg'); /* eslint-disable-next-line no-unused-vars */ @@ -21,6 +25,7 @@ const IASTNodeLocation = goog.requireType('Blockly.IASTNodeLocation'); * An AST node location SVG interface. * @interface * @extends {IASTNodeLocation} + * @alias Blockly.IASTNodeLocationSvg */ const IASTNodeLocationSvg = function() {}; diff --git a/core/interfaces/i_ast_node_location_with_block.js b/core/interfaces/i_ast_node_location_with_block.js index 11c71a70a..f9e00c385 100644 --- a/core/interfaces/i_ast_node_location_with_block.js +++ b/core/interfaces/i_ast_node_location_with_block.js @@ -12,6 +12,11 @@ 'use strict'; +/** + * The interface for an AST node location that has an associated + * block. + * @namespace Blockly.IASTNodeLocationWithBlock + */ goog.module('Blockly.IASTNodeLocationWithBlock'); /* eslint-disable-next-line no-unused-vars */ @@ -24,6 +29,7 @@ const {Block} = goog.requireType('Blockly.Block'); * An AST node location that has an associated block. * @interface * @extends {IASTNodeLocation} + * @alias Blockly.IASTNodeLocationWithBlock */ const IASTNodeLocationWithBlock = function() {}; diff --git a/core/interfaces/i_autohideable.js b/core/interfaces/i_autohideable.js index 3f2919d0f..467dac919 100644 --- a/core/interfaces/i_autohideable.js +++ b/core/interfaces/i_autohideable.js @@ -12,6 +12,11 @@ 'use strict'; +/** + * The interface for a component that is automatically hidden + * when WorkspaceSvg.hideChaff is called. + * @namespace Blockly.IAutoHideable + */ goog.module('Blockly.IAutoHideable'); /* eslint-disable-next-line no-unused-vars */ @@ -22,6 +27,7 @@ const IComponent = goog.requireType('Blockly.IComponent'); * Interface for a component that can be automatically hidden. * @extends {IComponent} * @interface + * @alias Blockly.IAutoHideable */ const IAutoHideable = function() {}; diff --git a/core/interfaces/i_block_dragger.js b/core/interfaces/i_block_dragger.js index d22f859cc..e5957e4ba 100644 --- a/core/interfaces/i_block_dragger.js +++ b/core/interfaces/i_block_dragger.js @@ -11,6 +11,10 @@ 'use strict'; +/** + * The interface for a block dragger. + * @namespace Blockly.IBlockDragger + */ goog.module('Blockly.IBlockDragger'); /* eslint-disable-next-line no-unused-vars */ @@ -22,6 +26,7 @@ const {BlockSvg} = goog.requireType('Blockly.BlockSvg'); /** * A block dragger interface. * @interface + * @alias Blockly.IBlockDragger */ const IBlockDragger = function() {}; diff --git a/core/interfaces/i_bounded_element.js b/core/interfaces/i_bounded_element.js index de1b3a663..081e16429 100644 --- a/core/interfaces/i_bounded_element.js +++ b/core/interfaces/i_bounded_element.js @@ -11,6 +11,10 @@ 'use strict'; +/** + * The interface for a bounded element. + * @namespace Blockly.IBoundedElement + */ goog.module('Blockly.IBoundedElement'); /* eslint-disable-next-line no-unused-vars */ @@ -20,6 +24,7 @@ const Rect = goog.requireType('Blockly.utils.Rect'); /** * A bounded element interface. * @interface + * @alias Blockly.IBoundedElement */ const IBoundedElement = function() {}; diff --git a/core/interfaces/i_bubble.js b/core/interfaces/i_bubble.js index a8b1cfafb..f443399fb 100644 --- a/core/interfaces/i_bubble.js +++ b/core/interfaces/i_bubble.js @@ -11,6 +11,10 @@ 'use strict'; +/** + * The interface for a bubble. + * @namespace Blockly.IBubble + */ goog.module('Blockly.IBubble'); /* eslint-disable-next-line no-unused-vars */ @@ -28,6 +32,7 @@ const {BlockDragSurfaceSvg} = goog.requireType('Blockly.BlockDragSurfaceSvg'); * @interface * @extends {IDraggable} * @extends {IContextMenu} + * @alias Blockly.IBubble */ const IBubble = function() {}; diff --git a/core/interfaces/i_collapsible_toolbox_item.js b/core/interfaces/i_collapsible_toolbox_item.js index af6bba3cc..a786d0956 100644 --- a/core/interfaces/i_collapsible_toolbox_item.js +++ b/core/interfaces/i_collapsible_toolbox_item.js @@ -11,6 +11,10 @@ 'use strict'; +/** + * The interface for a collapsible toolbox item. + * @namespace Blockly.ICollapsibleToolboxItem + */ goog.module('Blockly.ICollapsibleToolboxItem'); /* eslint-disable-next-line no-unused-vars */ @@ -23,6 +27,7 @@ const IToolboxItem = goog.requireType('Blockly.IToolboxItem'); * Interface for an item in the toolbox that can be collapsed. * @extends {ISelectableToolboxItem} * @interface + * @alias Blockly.ICollapsibleToolboxItem */ const ICollapsibleToolboxItem = function() {}; diff --git a/core/interfaces/i_component.js b/core/interfaces/i_component.js index 9711cd0a9..d6bbc1658 100644 --- a/core/interfaces/i_component.js +++ b/core/interfaces/i_component.js @@ -12,6 +12,11 @@ 'use strict'; +/** + * Interface for a workspace component that can be registered with + * the ComponentManager. + * @namespace Blockly.IComponent + */ goog.module('Blockly.IComponent'); @@ -19,6 +24,7 @@ goog.module('Blockly.IComponent'); * The interface for a workspace component that can be registered with the * ComponentManager. * @interface + * @alias Blockly.IComponent */ const IComponent = function() {}; diff --git a/core/interfaces/i_connection_checker.js b/core/interfaces/i_connection_checker.js index dafd36994..d0724e92d 100644 --- a/core/interfaces/i_connection_checker.js +++ b/core/interfaces/i_connection_checker.js @@ -11,6 +11,11 @@ */ 'use strict'; +/** + * The interface for an object that encapsulates logic for + * checking whether a potential connection is safe and valid. + * @namespace Blockly.IConnectionChecker + */ goog.module('Blockly.IConnectionChecker'); /* eslint-disable-next-line no-unused-vars */ @@ -22,6 +27,7 @@ const RenderedConnection = goog.requireType('Blockly.RenderedConnection'); /** * Class for connection type checking logic. * @interface + * @alias Blockly.IConnectionChecker */ const IConnectionChecker = function() {}; diff --git a/core/interfaces/i_contextmenu.js b/core/interfaces/i_contextmenu.js index 9a53d17a1..43831c281 100644 --- a/core/interfaces/i_contextmenu.js +++ b/core/interfaces/i_contextmenu.js @@ -11,11 +11,16 @@ 'use strict'; +/** + * The interface for an object that supports a right-click. + * @namespace Blockly.IContextMenu + */ goog.module('Blockly.IContextMenu'); /** * @interface + * @alias Blockly.IContextMenu */ const IContextMenu = function() {}; diff --git a/core/interfaces/i_copyable.js b/core/interfaces/i_copyable.js index 98b58e0ba..238f5bea6 100644 --- a/core/interfaces/i_copyable.js +++ b/core/interfaces/i_copyable.js @@ -11,6 +11,10 @@ 'use strict'; +/** + * The interface for an object that is copyable. + * @namespace Blockly.ICopyable + */ goog.module('Blockly.ICopyable'); /* eslint-disable-next-line no-unused-vars */ @@ -22,6 +26,7 @@ const WorkspaceSvg = goog.requireType('Blockly.WorkspaceSvg'); /** * @extends {ISelectable} * @interface + * @alias Blockly.ICopyable */ const ICopyable = function() {}; diff --git a/core/interfaces/i_deletable.js b/core/interfaces/i_deletable.js index 743d6ffd5..302ba89b4 100644 --- a/core/interfaces/i_deletable.js +++ b/core/interfaces/i_deletable.js @@ -11,12 +11,17 @@ 'use strict'; +/** + * The interface for an object that is deletable. + * @namespace Blockly.IDeletable + */ goog.module('Blockly.IDeletable'); /** * The interface for an object that can be deleted. * @interface + * @alias Blockly.IDeletable */ const IDeletable = function() {}; diff --git a/core/interfaces/i_delete_area.js b/core/interfaces/i_delete_area.js index ef4746c80..2049a7f66 100644 --- a/core/interfaces/i_delete_area.js +++ b/core/interfaces/i_delete_area.js @@ -12,6 +12,11 @@ 'use strict'; +/** + * The interface for a component that can delete a block or bubble + * that is dropped on top of it. + * @namespace Blockly.IDeleteArea + */ goog.module('Blockly.IDeleteArea'); /* eslint-disable-next-line no-unused-vars */ @@ -25,6 +30,7 @@ const IDragTarget = goog.requireType('Blockly.IDragTarget'); * on top of it. * @extends {IDragTarget} * @interface + * @alias Blockly.IDeleteArea */ const IDeleteArea = function() {}; diff --git a/core/interfaces/i_drag_target.js b/core/interfaces/i_drag_target.js index 782d01296..c72089990 100644 --- a/core/interfaces/i_drag_target.js +++ b/core/interfaces/i_drag_target.js @@ -12,6 +12,11 @@ 'use strict'; +/** + * The interface for a component that has a handler for when a + * block is dropped on top of it. + * @namespace Blockly.IDragTarget + */ goog.module('Blockly.IDragTarget'); /* eslint-disable-next-line no-unused-vars */ @@ -27,6 +32,7 @@ const Rect = goog.requireType('Blockly.utils.Rect'); * dragged over or dropped on top of it. * @extends {IComponent} * @interface + * @alias Blockly.IDragTarget */ const IDragTarget = function() {}; diff --git a/core/interfaces/i_draggable.js b/core/interfaces/i_draggable.js index 7dbb926d0..27d13549c 100644 --- a/core/interfaces/i_draggable.js +++ b/core/interfaces/i_draggable.js @@ -11,6 +11,10 @@ 'use strict'; +/** + * The interface for an object that is draggable. + * @namespace Blockly.IDraggable + */ goog.module('Blockly.IDraggable'); /* eslint-disable-next-line no-unused-vars */ @@ -21,6 +25,7 @@ const IDeletable = goog.requireType('Blockly.IDeletable'); * The interface for an object that can be dragged. * @extends {IDeletable} * @interface + * @alias Blockly.IDraggable */ const IDraggable = function() {}; diff --git a/core/interfaces/i_flyout.js b/core/interfaces/i_flyout.js index f4b8ad3c4..afbaf46fe 100644 --- a/core/interfaces/i_flyout.js +++ b/core/interfaces/i_flyout.js @@ -11,6 +11,10 @@ 'use strict'; +/** + * The interface for a flyout. + * @namespace Blockly.IFlyout + */ goog.module('Blockly.IFlyout'); /* eslint-disable-next-line no-unused-vars */ @@ -31,6 +35,7 @@ const {BlockSvg} = goog.requireType('Blockly.BlockSvg'); * Interface for a flyout. * @extends {IRegistrable} * @interface + * @alias Blockly.IFlyout */ const IFlyout = function() {}; diff --git a/core/interfaces/i_keyboard_accessible.js b/core/interfaces/i_keyboard_accessible.js index e935c01de..c58c03e0d 100644 --- a/core/interfaces/i_keyboard_accessible.js +++ b/core/interfaces/i_keyboard_accessible.js @@ -11,6 +11,10 @@ 'use strict'; +/** + * The interface for objects that handle keyboard shortcuts. + * @namespace Blockly.IKeyboardAccessible + */ goog.module('Blockly.IKeyboardAccessible'); /* eslint-disable-next-line no-unused-vars */ @@ -20,6 +24,7 @@ const ShortcutRegistry = goog.requireType('Blockly.ShortcutRegistry'); /** * An interface for an object that handles keyboard shortcuts. * @interface + * @alias Blockly.IKeyboardAccessible */ const IKeyboardAccessible = function() {}; diff --git a/core/interfaces/i_metrics_manager.js b/core/interfaces/i_metrics_manager.js index 9d707f7fb..e1d519b30 100644 --- a/core/interfaces/i_metrics_manager.js +++ b/core/interfaces/i_metrics_manager.js @@ -11,6 +11,10 @@ 'use strict'; +/** + * The interface for a metrics manager. + * @namespace Blockly.IMetricsManager + */ goog.module('Blockly.IMetricsManager'); /* eslint-disable-next-line no-unused-vars */ @@ -24,6 +28,7 @@ const Size = goog.requireType('Blockly.utils.Size'); /** * Interface for a metrics manager. * @interface + * @alias Blockly.IMetricsManager */ const IMetricsManager = function() {}; diff --git a/core/interfaces/i_movable.js b/core/interfaces/i_movable.js index b52f0aca2..8c8ce3cbc 100644 --- a/core/interfaces/i_movable.js +++ b/core/interfaces/i_movable.js @@ -11,12 +11,17 @@ 'use strict'; +/** + * The interface for an object that is movable. + * @namespace Blockly.IMovable + */ goog.module('Blockly.IMovable'); /** * The interface for an object that is movable. * @interface + * @alias Blockly.IMovable */ const IMovable = function() {}; diff --git a/core/interfaces/i_positionable.js b/core/interfaces/i_positionable.js index 26a8f26e6..95ef0cee3 100644 --- a/core/interfaces/i_positionable.js +++ b/core/interfaces/i_positionable.js @@ -11,6 +11,10 @@ 'use strict'; +/** + * The interface for a positionable UI element. + * @namespace Blockly.IPositionable + */ goog.module('Blockly.IPositionable'); /* eslint-disable-next-line no-unused-vars */ @@ -25,6 +29,7 @@ const Rect = goog.requireType('Blockly.utils.Rect'); * Interface for a component that is positioned on top of the workspace. * @extends {IComponent} * @interface + * @alias Blockly.IPositionable */ const IPositionable = function() {}; diff --git a/core/interfaces/i_registrable.js b/core/interfaces/i_registrable.js index 382ccbf29..573162024 100644 --- a/core/interfaces/i_registrable.js +++ b/core/interfaces/i_registrable.js @@ -12,12 +12,18 @@ 'use strict'; +/** + * The interface for a Blockly component that can be registered. + * (Ex. Toolbox, Fields, Renderers) + * @namespace Blockly.IRegistrable + */ goog.module('Blockly.IRegistrable'); /** * The interface for a Blockly component that can be registered. * @interface + * @alias Blockly.IRegistrable */ const IRegistrable = function() {}; diff --git a/core/interfaces/i_registrable_field.js b/core/interfaces/i_registrable_field.js index beb367462..3874861ba 100644 --- a/core/interfaces/i_registrable_field.js +++ b/core/interfaces/i_registrable_field.js @@ -11,6 +11,10 @@ 'use strict'; +/** + * The interface for a Blockly field that can be registered. + * @namespace Blockly.IRegistrableField + */ goog.module('Blockly.IRegistrableField'); /* eslint-disable-next-line no-unused-vars */ diff --git a/core/interfaces/i_selectable.js b/core/interfaces/i_selectable.js index 3b9d074a5..4a59fcd90 100644 --- a/core/interfaces/i_selectable.js +++ b/core/interfaces/i_selectable.js @@ -11,6 +11,10 @@ 'use strict'; +/** + * The interface for an object that is selectable. + * @namespace Blockly.ISelectable + */ goog.module('Blockly.ISelectable'); // eslint-disable-next-line no-unused-vars @@ -24,6 +28,7 @@ const IMovable = goog.requireType('Blockly.IMovable'); * @extends {IDeletable} * @extends {IMovable} * @interface + * @alias Blockly.ISelectable */ const ISelectable = function() {}; diff --git a/core/interfaces/i_selectable_toolbox_item.js b/core/interfaces/i_selectable_toolbox_item.js index 39fd08326..6fb6cc131 100644 --- a/core/interfaces/i_selectable_toolbox_item.js +++ b/core/interfaces/i_selectable_toolbox_item.js @@ -11,6 +11,10 @@ 'use strict'; +/** + * The interface for a selectable toolbox item. + * @namespace Blockly.ISelectableToolboxItem + */ goog.module('Blockly.ISelectableToolboxItem'); /* eslint-disable-next-line no-unused-vars */ @@ -23,6 +27,7 @@ const toolbox = goog.requireType('Blockly.utils.toolbox'); * Interface for an item in the toolbox that can be selected. * @extends {IToolboxItem} * @interface + * @alias Blockly.ISelectableToolboxItem */ const ISelectableToolboxItem = function() {}; diff --git a/core/interfaces/i_serializer.js b/core/interfaces/i_serializer.js index 5976e74b3..90b319b56 100644 --- a/core/interfaces/i_serializer.js +++ b/core/interfaces/i_serializer.js @@ -6,11 +6,16 @@ /** * @fileoverview The record type for an object containing functions for - * serializing part of the workspace. + * serializing part of the workspace. */ 'use strict'; +/** + * The record type for an object containing functions for + * serializing part of the workspace. + * @namespace Blockly.serialization.ISerializer + */ goog.module('Blockly.serialization.ISerializer'); goog.module.declareLegacyNamespace(); @@ -21,6 +26,7 @@ const Workspace = goog.requireType('Blockly.Workspace'); /** * Serializes and deserializes a plugin or system. * @interface + * @alias Blockly.serialization.ISerializer.ISerializer */ class ISerializer { constructor() { diff --git a/core/interfaces/i_styleable.js b/core/interfaces/i_styleable.js index 5d25bf713..df22f2424 100644 --- a/core/interfaces/i_styleable.js +++ b/core/interfaces/i_styleable.js @@ -11,12 +11,17 @@ 'use strict'; +/** + * The interface for an object that a style can be added to. + * @namespace Blockly.IStyleable + */ goog.module('Blockly.IStyleable'); /** * Interface for an object that a style can be added to. * @interface + * @alias Blockly.IStyleable */ const IStyleable = function() {}; diff --git a/core/interfaces/i_toolbox.js b/core/interfaces/i_toolbox.js index 7e8200386..6959b5c7a 100644 --- a/core/interfaces/i_toolbox.js +++ b/core/interfaces/i_toolbox.js @@ -11,6 +11,10 @@ 'use strict'; +/** + * The interface for a toolbox. + * @namespace Blockly.IToolbox + */ goog.module('Blockly.IToolbox'); /* eslint-disable-next-line no-unused-vars */ @@ -29,6 +33,7 @@ const toolbox = goog.requireType('Blockly.utils.toolbox'); * Interface for a toolbox. * @extends {IRegistrable} * @interface + * @alias Blockly.IToolbox */ const IToolbox = function() {}; diff --git a/core/interfaces/i_toolbox_item.js b/core/interfaces/i_toolbox_item.js index a3b946543..aa1744adb 100644 --- a/core/interfaces/i_toolbox_item.js +++ b/core/interfaces/i_toolbox_item.js @@ -11,12 +11,17 @@ 'use strict'; +/** + * The interface for a toolbox item. + * @namespace Blockly.IToolboxItem + */ goog.module('Blockly.IToolboxItem'); /** * Interface for an item in the toolbox. * @interface + * @alias Blockly.IToolboxItem */ const IToolboxItem = function() {}; diff --git a/core/internal_constants.js b/core/internal_constants.js index aa1596a4c..086d95f2a 100644 --- a/core/internal_constants.js +++ b/core/internal_constants.js @@ -12,6 +12,11 @@ */ 'use strict'; +/** + * Module that provides constants for use inside Blockly. Do not + * use these constants outside of the core library. + * @namespace Blockly.internalConstants + */ goog.module('Blockly.internalConstants'); const {ConnectionType} = goog.require('Blockly.ConnectionType'); @@ -20,6 +25,7 @@ const {ConnectionType} = goog.require('Blockly.ConnectionType'); /** * The multiplier for scroll wheel deltas using the line delta mode. * @type {number} + * @alias Blockly.internalConstants.LINE_MODE_MULTIPLIER */ const LINE_MODE_MULTIPLIER = 40; exports.LINE_MODE_MULTIPLIER = LINE_MODE_MULTIPLIER; @@ -27,12 +33,14 @@ exports.LINE_MODE_MULTIPLIER = LINE_MODE_MULTIPLIER; /** * The multiplier for scroll wheel deltas using the page delta mode. * @type {number} + * @alias Blockly.internalConstants.PAGE_MODE_MULTIPLIER */ const PAGE_MODE_MULTIPLIER = 125; exports.PAGE_MODE_MULTIPLIER = PAGE_MODE_MULTIPLIER; /** * Number of pixels the mouse must move before a drag starts. + * @alias Blockly.internalConstants.DRAG_RADIUS */ const DRAG_RADIUS = 5; exports.DRAG_RADIUS = DRAG_RADIUS; @@ -41,12 +49,14 @@ exports.DRAG_RADIUS = DRAG_RADIUS; * Number of pixels the mouse must move before a drag/scroll starts from the * flyout. Because the drag-intention is determined when this is reached, it is * larger than DRAG_RADIUS so that the drag-direction is clearer. + * @alias Blockly.internalConstants.FLYOUT_DRAG_RADIUS */ const FLYOUT_DRAG_RADIUS = 10; exports.FLYOUT_DRAG_RADIUS = FLYOUT_DRAG_RADIUS; /** * Maximum misalignment between connections for them to snap together. + * @alias Blockly.internalConstants.SNAP_RADIUS */ const SNAP_RADIUS = 28; exports.SNAP_RADIUS = SNAP_RADIUS; @@ -54,6 +64,7 @@ exports.SNAP_RADIUS = SNAP_RADIUS; /** * Maximum misalignment between connections for them to snap together, * when a connection is already highlighted. + * @alias Blockly.internalConstants.CONNECTING_SNAP_RADIUS */ const CONNECTING_SNAP_RADIUS = SNAP_RADIUS; exports.CONNECTING_SNAP_RADIUS = CONNECTING_SNAP_RADIUS; @@ -62,30 +73,35 @@ exports.CONNECTING_SNAP_RADIUS = CONNECTING_SNAP_RADIUS; * How much to prefer staying connected to the current connection over moving to * a new connection. The current previewed connection is considered to be this * much closer to the matching connection on the block than it actually is. + * @alias Blockly.internalConstants.CURRENT_CONNECTION_PREFERENCE */ const CURRENT_CONNECTION_PREFERENCE = 8; exports.CURRENT_CONNECTION_PREFERENCE = CURRENT_CONNECTION_PREFERENCE; /** * Delay in ms between trigger and bumping unconnected block out of alignment. + * @alias Blockly.internalConstants.BUMP_DELAY */ const BUMP_DELAY = 250; exports.BUMP_DELAY = BUMP_DELAY; /** * Maximum randomness in workspace units for bumping a block. + * @alias Blockly.internalConstants.BUMP_RANDOMNESS */ const BUMP_RANDOMNESS = 10; exports.BUMP_RANDOMNESS = BUMP_RANDOMNESS; /** * Number of characters to truncate a collapsed block to. + * @alias Blockly.internalConstants.COLLAPSE_CHARS */ const COLLAPSE_CHARS = 30; exports.COLLAPSE_CHARS = COLLAPSE_CHARS; /** * Length in ms for a touch to become a long press. + * @alias Blockly.internalConstants.LONGPRESS */ const LONGPRESS = 750; exports.LONGPRESS = LONGPRESS; @@ -93,6 +109,7 @@ exports.LONGPRESS = LONGPRESS; /** * Prevent a sound from playing if another sound preceded it within this many * milliseconds. + * @alias Blockly.internalConstants.SOUND_LIMIT */ const SOUND_LIMIT = 100; exports.SOUND_LIMIT = SOUND_LIMIT; @@ -100,6 +117,7 @@ exports.SOUND_LIMIT = SOUND_LIMIT; /** * When dragging a block out of a stack, split the stack in two (true), or drag * out the block healing the stack (false). + * @alias Blockly.internalConstants.DRAG_STACK */ const DRAG_STACK = true; exports.DRAG_STACK = DRAG_STACK; @@ -107,6 +125,7 @@ exports.DRAG_STACK = DRAG_STACK; /** * The richness of block colours, regardless of the hue. * Must be in the range of 0 (inclusive) to 1 (exclusive). + * @alias Blockly.internalConstants.HSV_SATURATION */ const HSV_SATURATION = 0.45; exports.HSV_SATURATION = HSV_SATURATION; @@ -114,12 +133,14 @@ exports.HSV_SATURATION = HSV_SATURATION; /** * The intensity of block colours, regardless of the hue. * Must be in the range of 0 (inclusive) to 1 (exclusive). + * @alias Blockly.internalConstants.HSV_VALUE */ const HSV_VALUE = 0.65; exports.HSV_VALUE = HSV_VALUE; /** * Sprited icons and images. + * @alias Blockly.internalConstants.SPRITE */ const SPRITE = { width: 96, @@ -131,6 +152,7 @@ exports.SPRITE = SPRITE; /** * ENUM for no drag operation. * @const + * @alias Blockly.internalConstants.DRAG_NONE */ const DRAG_NONE = 0; exports.DRAG_NONE = DRAG_NONE; @@ -138,6 +160,7 @@ exports.DRAG_NONE = DRAG_NONE; /** * ENUM for inside the sticky DRAG_RADIUS. * @const + * @alias Blockly.internalConstants.DRAG_STICKY */ const DRAG_STICKY = 1; exports.DRAG_STICKY = DRAG_STICKY; @@ -146,6 +169,7 @@ exports.DRAG_STICKY = DRAG_STICKY; * ENUM for inside the non-sticky DRAG_RADIUS, for differentiating between * clicks and drags. * @const + * @alias Blockly.internalConstants.DRAG_BEGIN */ const DRAG_BEGIN = 1; exports.DRAG_BEGIN = DRAG_BEGIN; @@ -153,6 +177,7 @@ exports.DRAG_BEGIN = DRAG_BEGIN; /** * ENUM for freely draggable (outside the DRAG_RADIUS, if one applies). * @const + * @alias Blockly.internalConstants.DRAG_FREE */ const DRAG_FREE = 2; exports.DRAG_FREE = DRAG_FREE; @@ -160,6 +185,7 @@ exports.DRAG_FREE = DRAG_FREE; /** * Lookup table for determining the opposite type of a connection. * @const + * @alias Blockly.internalConstants.OPPOSITE_TYPE */ const OPPOSITE_TYPE = []; OPPOSITE_TYPE[ConnectionType.INPUT_VALUE] = ConnectionType.OUTPUT_VALUE; @@ -176,6 +202,7 @@ exports.OPPOSITE_TYPE = OPPOSITE_TYPE; * This string indicates that the category should be dynamically populated with * variable blocks. * @const {string} + * @alias Blockly.internalConstants.VARIABLE_CATEGORY_NAME */ const VARIABLE_CATEGORY_NAME = 'VARIABLE'; exports.VARIABLE_CATEGORY_NAME = VARIABLE_CATEGORY_NAME; @@ -185,6 +212,7 @@ exports.VARIABLE_CATEGORY_NAME = VARIABLE_CATEGORY_NAME; * This string indicates that the category should be dynamically populated with * variable blocks. * @const {string} + * @alias Blockly.internalConstants.VARIABLE_DYNAMIC_CATEGORY_NAME */ const VARIABLE_DYNAMIC_CATEGORY_NAME = 'VARIABLE_DYNAMIC'; exports.VARIABLE_DYNAMIC_CATEGORY_NAME = VARIABLE_DYNAMIC_CATEGORY_NAME; @@ -194,6 +222,7 @@ exports.VARIABLE_DYNAMIC_CATEGORY_NAME = VARIABLE_DYNAMIC_CATEGORY_NAME; * This string indicates that the category should be dynamically populated with * procedure blocks. * @const {string} + * @alias Blockly.internalConstants.PROCEDURE_CATEGORY_NAME */ const PROCEDURE_CATEGORY_NAME = 'PROCEDURE'; exports.PROCEDURE_CATEGORY_NAME = PROCEDURE_CATEGORY_NAME; @@ -203,6 +232,7 @@ exports.PROCEDURE_CATEGORY_NAME = PROCEDURE_CATEGORY_NAME; * This string indicates that this option in the dropdown is 'Rename * variable...' and if selected, should trigger the prompt to rename a variable. * @const {string} + * @alias Blockly.internalConstants.RENAME_VARIABLE_ID */ const RENAME_VARIABLE_ID = 'RENAME_VARIABLE_ID'; exports.RENAME_VARIABLE_ID = RENAME_VARIABLE_ID; @@ -212,6 +242,7 @@ exports.RENAME_VARIABLE_ID = RENAME_VARIABLE_ID; * This string indicates that this option in the dropdown is 'Delete the "%1" * variable' and if selected, should trigger the prompt to delete a variable. * @const {string} + * @alias Blockly.internalConstants.DELETE_VARIABLE_ID */ const DELETE_VARIABLE_ID = 'DELETE_VARIABLE_ID'; exports.DELETE_VARIABLE_ID = DELETE_VARIABLE_ID; diff --git a/core/keyboard_nav/ast_node.js b/core/keyboard_nav/ast_node.js index 2bbe33d02..68225944b 100644 --- a/core/keyboard_nav/ast_node.js +++ b/core/keyboard_nav/ast_node.js @@ -10,6 +10,11 @@ */ 'use strict'; +/** + * The class representing an AST node. + * Used to traverse the Blockly AST. + * @namespace Blockly.ASTNode + */ goog.module('Blockly.ASTNode'); /* eslint-disable-next-line no-unused-vars */ @@ -39,6 +44,7 @@ const {ConnectionType} = goog.require('Blockly.ConnectionType'); * @param {!IASTNodeLocation} location The position in the AST. * @param {!ASTNode.Params=} opt_params Optional dictionary of options. * @constructor + * @alias Blockly.ASTNode */ const ASTNode = function(type, location, opt_params) { if (!location) { diff --git a/core/keyboard_nav/basic_cursor.js b/core/keyboard_nav/basic_cursor.js index 6cb8165f6..24fd87468 100644 --- a/core/keyboard_nav/basic_cursor.js +++ b/core/keyboard_nav/basic_cursor.js @@ -11,6 +11,11 @@ */ 'use strict'; +/** + * The class representing a basic cursor. + * Used to demo switching between different cursors. + * @namespace Blockly.BasicCursor + */ goog.module('Blockly.BasicCursor'); const object = goog.require('Blockly.utils.object'); @@ -25,6 +30,7 @@ const {Cursor} = goog.require('Blockly.Cursor'); * previous. * @constructor * @extends {Cursor} + * @alias Blockly.BasicCursor */ const BasicCursor = function() { BasicCursor.superClass_.constructor.call(this); diff --git a/core/keyboard_nav/cursor.js b/core/keyboard_nav/cursor.js index 120e676ce..900353e46 100644 --- a/core/keyboard_nav/cursor.js +++ b/core/keyboard_nav/cursor.js @@ -11,6 +11,11 @@ */ 'use strict'; +/** + * The class representing a cursor. + * Used primarily for keyboard navigation. + * @namespace Blockly.Cursor + */ goog.module('Blockly.Cursor'); const object = goog.require('Blockly.utils.object'); @@ -23,6 +28,7 @@ const {Marker} = goog.require('Blockly.Marker'); * A cursor controls how a user navigates the Blockly AST. * @constructor * @extends {Marker} + * @alias Blockly.Cursor */ const Cursor = function() { Cursor.superClass_.constructor.call(this); diff --git a/core/keyboard_nav/marker.js b/core/keyboard_nav/marker.js index 954b22968..6bac4606b 100644 --- a/core/keyboard_nav/marker.js +++ b/core/keyboard_nav/marker.js @@ -11,6 +11,11 @@ */ 'use strict'; +/** + * The class representing a marker. + * Used primarily for keyboard navigation to show a marked location. + * @namespace Blockly.Marker + */ goog.module('Blockly.Marker'); /* eslint-disable-next-line no-unused-vars */ @@ -23,6 +28,7 @@ const {ASTNode} = goog.requireType('Blockly.ASTNode'); * Class for a marker. * This is used in keyboard navigation to save a location in the Blockly AST. * @constructor + * @alias Blockly.Marker */ const Marker = function() { /** diff --git a/core/keyboard_nav/tab_navigate_cursor.js b/core/keyboard_nav/tab_navigate_cursor.js index ab49aadd5..91757f464 100644 --- a/core/keyboard_nav/tab_navigate_cursor.js +++ b/core/keyboard_nav/tab_navigate_cursor.js @@ -11,6 +11,11 @@ */ 'use strict'; +/** + * The class representing a cursor that is used to navigate + * between tab navigable fields. + * @namespace Blockly.TabNavigateCursor + */ goog.module('Blockly.TabNavigateCursor'); /* eslint-disable-next-line no-unused-vars */ @@ -24,6 +29,7 @@ const {BasicCursor} = goog.require('Blockly.BasicCursor'); * A cursor for navigating between tab navigable fields. * @constructor * @extends {BasicCursor} + * @alias Blockly.TabNavigateCursor */ const TabNavigateCursor = function() { TabNavigateCursor.superClass_.constructor.call(this); diff --git a/core/marker_manager.js b/core/marker_manager.js index f26365e0e..6e7374783 100644 --- a/core/marker_manager.js +++ b/core/marker_manager.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Object in charge of managing markers and the cursor. + * @namespace Blockly.MarkerManager + */ goog.module('Blockly.MarkerManager'); /* eslint-disable-next-line no-unused-vars */ @@ -24,6 +28,7 @@ const {Marker} = goog.requireType('Blockly.Marker'); * Class to manage the multiple markers and the cursor on a workspace. * @param {!WorkspaceSvg} workspace The workspace for the marker manager. * @constructor + * @alias Blockly.MarkerManager */ const MarkerManager = function(workspace) { /** diff --git a/core/menu.js b/core/menu.js index a142d341a..b6e2ba8f5 100644 --- a/core/menu.js +++ b/core/menu.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Blockly menu similar to Closure's goog.ui.Menu + * @namespace Blockly.Menu + */ goog.module('Blockly.Menu'); const Coordinate = goog.require('Blockly.utils.Coordinate'); @@ -27,6 +31,7 @@ const style = goog.require('Blockly.utils.style'); /** * A basic menu class. * @constructor + * @alias Blockly.Menu */ const Menu = function() { /** diff --git a/core/menuitem.js b/core/menuitem.js index a34148836..2baa75e85 100644 --- a/core/menuitem.js +++ b/core/menuitem.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Blockly menu item similar to Closure's goog.ui.MenuItem + * @namespace Blockly.MenuItem + */ goog.module('Blockly.MenuItem'); const aria = goog.require('Blockly.utils.aria'); @@ -24,6 +28,7 @@ const idGenerator = goog.require('Blockly.utils.idGenerator'); * of the item, or a HTML element to display. * @param {string=} opt_value Data/model associated with the menu item. * @constructor + * @alias Blockly.MenuItem */ const MenuItem = function(content, opt_value) { /** diff --git a/core/metrics_manager.js b/core/metrics_manager.js index 6331867af..b13ae3767 100644 --- a/core/metrics_manager.js +++ b/core/metrics_manager.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Calculates and reports workspace metrics. + * @namespace Blockly.MetricsManager + */ goog.module('Blockly.MetricsManager'); /* eslint-disable-next-line no-unused-vars */ @@ -33,6 +37,7 @@ const toolboxUtils = goog.require('Blockly.utils.toolbox'); * for. * @implements {IMetricsManager} * @constructor + * @alias Blockly.MetricsManager */ const MetricsManager = function(workspace) { /** diff --git a/core/msg.js b/core/msg.js index ff2de0fc3..e63070f2b 100644 --- a/core/msg.js +++ b/core/msg.js @@ -11,8 +11,8 @@ 'use strict'; /** - * Name space for the Msg singleton. - * Msg gets populated in the message files. + * Empty name space for the Message singleton. + * @namespace Blockly.Msg */ goog.module('Blockly.Msg'); goog.module.declareLegacyNamespace(); diff --git a/core/mutator.js b/core/mutator.js index c605608a4..c4d1c5443 100644 --- a/core/mutator.js +++ b/core/mutator.js @@ -11,6 +11,11 @@ */ 'use strict'; +/** + * Object representing a mutator dialog. A mutator allows the + * user to change the shape of a block using a nested blocks editor. + * @namespace Blockly.Mutator + */ goog.module('Blockly.Mutator'); /* eslint-disable-next-line no-unused-vars */ @@ -48,6 +53,7 @@ goog.require('Blockly.Events.BubbleOpen'); * @param {!Array} quarkNames List of names of sub-blocks for flyout. * @extends {Icon} * @constructor + * @alias Blockly.Mutator */ const Mutator = function(quarkNames) { Mutator.superClass_.constructor.call(this, null); diff --git a/core/names.js b/core/names.js index 099d2972d..ad567f4a5 100644 --- a/core/names.js +++ b/core/names.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Utility functions for handling variable and procedure names. + * @namespace Blockly.Names + */ goog.module('Blockly.Names'); const Msg = goog.require('Blockly.Msg'); @@ -30,6 +34,7 @@ goog.requireType('Blockly.Procedures'); * @param {string=} opt_variablePrefix Some languages need a '$' or a namespace * before all variable names (but not procedure names). * @constructor + * @alias Blockly.Names */ const Names = function(reservedWords, opt_variablePrefix) { this.variablePrefix_ = opt_variablePrefix || ''; diff --git a/core/options.js b/core/options.js index 75eba6956..d4fe2dc79 100644 --- a/core/options.js +++ b/core/options.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Object that controls settings for the workspace. + * @namespace Blockly.Options + */ goog.module('Blockly.Options'); /* eslint-disable-next-line no-unused-vars */ @@ -32,6 +36,7 @@ const toolbox = goog.require('Blockly.utils.toolbox'); * Specification: * https://developers.google.com/blockly/guides/get-started/web#configuration * @constructor + * @alias Blockly.Options */ const Options = function(options) { let toolboxJsonDef = null; diff --git a/core/positionable_helpers.js b/core/positionable_helpers.js index aa5bb8fcb..d162dafdd 100644 --- a/core/positionable_helpers.js +++ b/core/positionable_helpers.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Utility functions for positioning UI elements. + * @namespace Blockly.uiPosition + */ goog.module('Blockly.uiPosition'); /* eslint-disable-next-line no-unused-vars */ @@ -26,6 +30,7 @@ const toolbox = goog.require('Blockly.utils.toolbox'); /** * Enum for vertical positioning. * @enum {number} + * @alias Blockly.uiPosition.verticalPosition */ const verticalPosition = { TOP: 0, @@ -37,6 +42,7 @@ exports.verticalPosition = verticalPosition; /** * Enum for horizontal positioning. * @enum {number} + * @alias Blockly.uiPosition.horizontalPosition */ const horizontalPosition = { LEFT: 0, @@ -59,6 +65,7 @@ exports.Position = Position; /** * Enum for bump rules to use for dealing with collisions. * @enum {number} + * @alias Blockly.uiPosition.bumpDirection */ const bumpDirection = { UP: 0, @@ -81,6 +88,7 @@ exports.bumpDirection = bumpDirection; * @param {!MetricsManager.UiMetrics} metrics The workspace UI metrics. * @param {!WorkspaceSvg} workspace The workspace. * @return {!Rect} The suggested start position. + * @alias Blockly.uiPosition.getStartPositionRect */ const getStartPositionRect = function( position, size, horizontalPadding, verticalPadding, metrics, workspace) { @@ -125,6 +133,7 @@ exports.getStartPositionRect = getStartPositionRect; * @param {!WorkspaceSvg} workspace The workspace. * @param {!MetricsManager.UiMetrics} metrics The workspace metrics. * @return {!Position} The suggested corner position. + * @alias Blockly.uiPosition.getCornerOppositeToolbox */ const getCornerOppositeToolbox = function(workspace, metrics) { const leftCorner = @@ -150,6 +159,7 @@ exports.getCornerOppositeToolbox = getCornerOppositeToolbox; * @param {!Array} savedPositions List of rectangles that * represent the positions of UI elements already placed. * @return {!Rect} The suggested position rectangle. + * @alias Blockly.uiPosition.bumpPositionRect */ const bumpPositionRect = function(startRect, margin, bumpDir, savedPositions) { let top = startRect.top; diff --git a/core/procedures.js b/core/procedures.js index ff2081860..78fe0d0ea 100644 --- a/core/procedures.js +++ b/core/procedures.js @@ -11,8 +11,8 @@ 'use strict'; /** - * @name Blockly.Procedures - * @namespace + * Utility functions for handling procedures. + * @namespace Blockly.Procedures */ goog.module('Blockly.Procedures'); diff --git a/core/registry.js b/core/registry.js index 99f2e4e8b..5b2865575 100644 --- a/core/registry.js +++ b/core/registry.js @@ -11,6 +11,11 @@ */ 'use strict'; +/** + * This file is a universal registry that provides generic methods + * for registering and unregistering different types of classes. + * @namespace Blockly.registry + */ goog.module('Blockly.registry'); /* eslint-disable-next-line no-unused-vars */ @@ -62,6 +67,7 @@ const nameMap = Object.create(null); /** * The string used to register the default class for a type of plugin. * @type {string} + * @alias Blockly.registry.DEFAULT */ const DEFAULT = 'default'; exports.DEFAULT = DEFAULT; @@ -71,6 +77,7 @@ exports.DEFAULT = DEFAULT; * @param {string} name The name of the registry type. * @constructor * @template T + * @alias Blockly.registry.Type */ const Type = function(name) { /** @@ -145,6 +152,7 @@ Type.SERIALIZER = new Type('serializer'); * already been registered, or if the given class or object is not valid for * its type. * @template T + * @alias Blockly.registry.register */ const register = function(type, name, registryItem, opt_allowOverrides) { if ((!(type instanceof Type) && typeof type != 'string') || @@ -209,6 +217,7 @@ const validate = function(type, registryItem) { * (e.g. Field, Renderer) * @param {string} name The plugin's name. (Ex. field_angle, geras) * @template T + * @alias Blockly.registry.unregister */ const unregister = function(type, name) { type = String(type).toLowerCase(); @@ -263,6 +272,7 @@ const getItem = function(type, name, opt_throwIfMissing) { * @return {boolean} True if the registry has an item with the given type and * name, false otherwise. * @template T + * @alias Blockly.registry.hasItem */ const hasItem = function(type, name) { type = String(type).toLowerCase(); @@ -285,6 +295,7 @@ exports.hasItem = hasItem; * @return {?function(new:T, ...?)} The class with the given name and type or * null if none exists. * @template T + * @alias Blockly.registry.getClass */ const getClass = function(type, name, opt_throwIfMissing) { return /** @type {?function(new:T, ...?)} */ ( @@ -301,6 +312,7 @@ exports.getClass = getClass; * are unable to find the object. * @return {?T} The object with the given name and type or null if none exists. * @template T + * @alias Blockly.registry.getObject */ const getObject = function(type, name, opt_throwIfMissing) { return /** @type {T} */ (getItem(type, name, opt_throwIfMissing)); @@ -317,6 +329,7 @@ exports.getObject = getObject; * @return {?Object} A map of objects with * the given type, or null if none exists. * @template T + * @alias Blockly.registry.getAllItems */ const getAllItems = function(type, opt_cased, opt_throwIfMissing) { type = String(type).toLowerCase(); @@ -354,6 +367,7 @@ exports.getAllItems = getAllItems; * are unable to find the plugin. * @return {?function(new:T, ...?)} The class for the plugin. * @template T + * @alias Blockly.registry.getClassFromOptions */ const getClassFromOptions = function(type, options, opt_throwIfMissing) { const typeName = type.toString(); diff --git a/core/rendered_connection.js b/core/rendered_connection.js index da509e4e9..f04dcd02f 100644 --- a/core/rendered_connection.js +++ b/core/rendered_connection.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Components for creating connections between blocks. + * @namespace Blockly.RenderedConnection + */ goog.module('Blockly.RenderedConnection'); const Connection = goog.require('Blockly.Connection'); @@ -38,6 +42,7 @@ const {ConnectionType} = goog.require('Blockly.ConnectionType'); * @param {number} type The type of the connection. * @extends {Connection} * @constructor + * @alias Blockly.RenderedConnection */ const RenderedConnection = function(source, type) { RenderedConnection.superClass_.constructor.call(this, source, type); diff --git a/core/renderers/common/block_rendering.js b/core/renderers/common/block_rendering.js index b1bfa911e..9144204a6 100644 --- a/core/renderers/common/block_rendering.js +++ b/core/renderers/common/block_rendering.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Namespace for block rendering functionality. + * @namespace Blockly.blockRendering + */ goog.module('Blockly.blockRendering'); const BottomRow = goog.require('Blockly.blockRendering.BottomRow'); @@ -51,6 +55,7 @@ const registry = goog.require('Blockly.registry'); /** * Returns whether the debugger is turned on. * @return {boolean} Whether the debugger is turned on. + * @alias Blockly.blockRendering.isDebuggerEnabled */ const isDebuggerEnabled = function() { deprecation.warn( @@ -76,6 +81,7 @@ exports.register = register; /** * Unregisters the renderer registered with the given name. * @param {string} name The name of the renderer. + * @alias Blockly.blockRendering.unregister */ const unregister = function(name) { registry.unregister(registry.Type.RENDERER, name); @@ -85,6 +91,7 @@ exports.unregister = unregister; /** * Turn on the blocks debugger. * @package + * @alias Blockly.blockRendering.startDebugger */ const startDebugger = function() { deprecation.warn( @@ -98,6 +105,7 @@ exports.startDebugger = startDebugger; /** * Turn off the blocks debugger. * @package + * @alias Blockly.blockRendering.stopDebugger */ const stopDebugger = function() { deprecation.warn( @@ -116,6 +124,7 @@ exports.stopDebugger = stopDebugger; * @return {!Renderer} The new instance of a renderer. * Already initialized. * @package + * @alias Blockly.blockRendering.init */ const init = function(name, theme, opt_rendererOverrides) { const rendererClass = registry.getClass(registry.Type.RENDERER, name); diff --git a/core/renderers/common/constants.js b/core/renderers/common/constants.js index 8926ef92e..c65f6a38a 100644 --- a/core/renderers/common/constants.js +++ b/core/renderers/common/constants.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * An object that provides constants for rendering blocks. + * @namespace Blockly.blockRendering.ConstantProvider + */ goog.module('Blockly.blockRendering.ConstantProvider'); /* eslint-disable-next-line no-unused-vars */ @@ -30,6 +34,7 @@ const {ConnectionType} = goog.require('Blockly.ConnectionType'); * An object that provides constants for rendering blocks. * @constructor * @package + * @alias Blockly.blockRendering.ConstantProvider */ const ConstantProvider = function() { /** diff --git a/core/renderers/common/debug.js b/core/renderers/common/debug.js index 34c51224d..499b12732 100644 --- a/core/renderers/common/debug.js +++ b/core/renderers/common/debug.js @@ -9,6 +9,10 @@ */ 'use strict'; +/** + * Block rendering debugging functionality. + * @namespace Blockly.blockRendering.debug + */ goog.module('Blockly.blockRendering.debug'); @@ -20,6 +24,7 @@ let useDebugger = false; /** * Returns whether the debugger is turned on. * @return {boolean} Whether the debugger is turned on. + * @alias Blockly.blockRendering.debug.isDebuggerEnabled */ const isDebuggerEnabled = function() { return useDebugger; @@ -30,6 +35,7 @@ exports.isDebuggerEnabled = isDebuggerEnabled; /** * Turn on the blocks debugger. * @package + * @alias Blockly.blockRendering.debug.startDebugger */ const startDebugger = function() { useDebugger = true; @@ -40,6 +46,7 @@ exports.startDebugger = startDebugger; /** * Turn off the blocks debugger. * @package + * @alias Blockly.blockRendering.debug.stopDebugger */ const stopDebugger = function() { useDebugger = false; diff --git a/core/renderers/common/debugger.js b/core/renderers/common/debugger.js index 5841887a1..03fc7cba9 100644 --- a/core/renderers/common/debugger.js +++ b/core/renderers/common/debugger.js @@ -5,11 +5,15 @@ */ /** - * @fileoverview Methods for graphically rendering a block as SVG. + * @fileoverview Methods for rendering debug graphics. * @author fenichel@google.com (Rachel Fenichel) */ 'use strict'; +/** + * Methods for rendering debug graphics. + * @namespace Blockly.blockRendering.Debug + */ goog.module('Blockly.blockRendering.Debug'); /* eslint-disable-next-line no-unused-vars */ @@ -39,6 +43,7 @@ const {ConnectionType} = goog.require('Blockly.ConnectionType'); * constants. * @package * @constructor + * @alias Blockly.blockRendering.Debug */ const Debug = function(constants) { /** diff --git a/core/renderers/common/drawer.js b/core/renderers/common/drawer.js index 075de23b2..f1e4db189 100644 --- a/core/renderers/common/drawer.js +++ b/core/renderers/common/drawer.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Methods for graphically rendering a block as SVG. + * @namespace Blockly.blockRendering.Drawer + */ goog.module('Blockly.blockRendering.Drawer'); /* eslint-disable-next-line no-unused-vars */ @@ -38,6 +42,7 @@ const {BlockSvg} = goog.requireType('Blockly.BlockSvg'); * information needed to render this block. * @package * @constructor + * @alias Blockly.blockRendering.Drawer */ const Drawer = function(block, info) { this.block_ = block; diff --git a/core/renderers/common/i_path_object.js b/core/renderers/common/i_path_object.js index eddf0c593..a36b9f209 100644 --- a/core/renderers/common/i_path_object.js +++ b/core/renderers/common/i_path_object.js @@ -12,6 +12,11 @@ 'use strict'; +/** + * The interface for an object that owns a block's rendering SVG + * elements. + * @namespace Blockly.blockRendering.IPathObject + */ goog.module('Blockly.blockRendering.IPathObject'); /* eslint-disable-next-line no-unused-vars */ @@ -28,6 +33,7 @@ const {Block} = goog.requireType('Blockly.Block'); * @param {!ConstantProvider} _constants The renderer's * constants. * @interface + * @alias Blockly.blockRendering.IPathObject */ const IPathObject = function(_root, _constants) {}; diff --git a/core/renderers/common/info.js b/core/renderers/common/info.js index d47660579..b9e595f73 100644 --- a/core/renderers/common/info.js +++ b/core/renderers/common/info.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Methods for graphically rendering a block as SVG. + * @namespace Blockly.blockRendering.RenderInfo + */ goog.module('Blockly.blockRendering.RenderInfo'); const BottomRow = goog.require('Blockly.blockRendering.BottomRow'); @@ -59,6 +63,7 @@ const {BlockSvg} = goog.requireType('Blockly.BlockSvg'); * @param {!BlockSvg} block The block to measure. * @constructor * @package + * @alias Blockly.blockRendering.RenderInfo */ const RenderInfo = function(renderer, block) { this.block_ = block; diff --git a/core/renderers/common/marker_svg.js b/core/renderers/common/marker_svg.js index 770b57a6c..afcffe7a4 100644 --- a/core/renderers/common/marker_svg.js +++ b/core/renderers/common/marker_svg.js @@ -11,6 +11,10 @@ 'use strict'; +/** + * Methods for graphically rendering a marker as SVG. + * @namespace Blockly.blockRendering.MarkerSvg + */ goog.module('Blockly.blockRendering.MarkerSvg'); /* eslint-disable-next-line no-unused-vars */ @@ -65,6 +69,7 @@ const HEIGHT_MULTIPLIER = 3 / 4; * the renderer. * @param {!Marker} marker The marker to draw. * @constructor + * @alias Blockly.blockRendering.MarkerSvg */ const MarkerSvg = function(workspace, constants, marker) { /** diff --git a/core/renderers/common/path_object.js b/core/renderers/common/path_object.js index 2c98e9e93..3d4345005 100644 --- a/core/renderers/common/path_object.js +++ b/core/renderers/common/path_object.js @@ -11,6 +11,10 @@ 'use strict'; +/** + * An object that owns a block's rendering SVG elements. + * @namespace Blockly.blockRendering.PathObject + */ goog.module('Blockly.blockRendering.PathObject'); /* eslint-disable-next-line no-unused-vars */ @@ -38,6 +42,7 @@ const {Block} = goog.requireType('Blockly.Block'); * @constructor * @implements {IPathObject} * @package + * @alias Blockly.blockRendering.PathObject */ const PathObject = function(root, style, constants) { /** diff --git a/core/renderers/common/renderer.js b/core/renderers/common/renderer.js index 223aba231..11d1beb5a 100644 --- a/core/renderers/common/renderer.js +++ b/core/renderers/common/renderer.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Base renderer. + * @namespace Blockly.blockRendering.Renderer + */ goog.module('Blockly.blockRendering.Renderer'); const Connection = goog.require('Blockly.Connection'); @@ -48,6 +52,7 @@ const {Marker} = goog.requireType('Blockly.Marker'); * @package * @constructor * @implements {IRegistrable} + * @alias Blockly.blockRendering.Renderer */ const Renderer = function(name) { /** diff --git a/core/renderers/geras/constants.js b/core/renderers/geras/constants.js index cb5011367..f781d0031 100644 --- a/core/renderers/geras/constants.js +++ b/core/renderers/geras/constants.js @@ -11,6 +11,11 @@ */ 'use strict'; +/** + * An object that provides constants for rendering blocks in Geras + * mode. + * @namespace Blockly.geras.ConstantProvider + */ goog.module('Blockly.geras.ConstantProvider'); const BaseConstantProvider = goog.require('Blockly.blockRendering.ConstantProvider'); @@ -22,6 +27,7 @@ const object = goog.require('Blockly.utils.object'); * @constructor * @package * @extends {BaseConstantProvider} + * @alias Blockly.geras.ConstantProvider */ const ConstantProvider = function() { ConstantProvider.superClass_.constructor.call(this); diff --git a/core/renderers/geras/drawer.js b/core/renderers/geras/drawer.js index 9851cdd2b..32dd0ef72 100644 --- a/core/renderers/geras/drawer.js +++ b/core/renderers/geras/drawer.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Renderer that preserves the look and feel of Blockly pre-2019. + * @namespace Blockly.geras.Drawer + */ goog.module('Blockly.geras.Drawer'); const BaseDrawer = goog.require('Blockly.blockRendering.Drawer'); @@ -33,6 +37,7 @@ const {BlockSvg} = goog.requireType('Blockly.BlockSvg'); * @package * @constructor * @extends {BaseDrawer} + * @alias Blockly.geras.Drawer */ const Drawer = function(block, info) { Drawer.superClass_.constructor.call(this, block, info); diff --git a/core/renderers/geras/geras.js b/core/renderers/geras/geras.js index c15aff155..02639276f 100644 --- a/core/renderers/geras/geras.js +++ b/core/renderers/geras/geras.js @@ -9,6 +9,10 @@ */ 'use strict'; +/** + * Re-exports of Blockly.geras.* modules. + * @namespace Blockly.geras + */ goog.module('Blockly.geras'); const ConstantProvider = goog.require('Blockly.geras.ConstantProvider'); diff --git a/core/renderers/geras/highlight_constants.js b/core/renderers/geras/highlight_constants.js index 46cf341b1..a472cad44 100644 --- a/core/renderers/geras/highlight_constants.js +++ b/core/renderers/geras/highlight_constants.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Objects for rendering highlights on blocks. + * @namespace Blockly.geras.HighlightConstantProvider + */ goog.module('Blockly.geras.HighlightConstantProvider'); /* eslint-disable-next-line no-unused-vars */ @@ -26,6 +30,7 @@ const svgPaths = goog.require('Blockly.utils.svgPaths'); * constants provider. * @constructor * @package + * @alias Blockly.geras.HighlightConstantProvider */ const HighlightConstantProvider = function(constants) { /** diff --git a/core/renderers/geras/highlighter.js b/core/renderers/geras/highlighter.js index 8b6d9f63a..8280c36fd 100644 --- a/core/renderers/geras/highlighter.js +++ b/core/renderers/geras/highlighter.js @@ -11,6 +11,11 @@ */ 'use strict'; +/** + * Methods for adding highlights on block, for rendering in + * compatibility mode. + * @namespace Blockly.geras.Highlighter + */ goog.module('Blockly.geras.Highlighter'); /* eslint-disable-next-line no-unused-vars */ @@ -40,6 +45,7 @@ const svgPaths = goog.require('Blockly.utils.svgPaths'); * information needed to render this block. * @package * @constructor + * @alias Blockly.geras.Highlighter */ const Highlighter = function(info) { this.info_ = info; diff --git a/core/renderers/geras/info.js b/core/renderers/geras/info.js index e5edc0fa6..8c861bde6 100644 --- a/core/renderers/geras/info.js +++ b/core/renderers/geras/info.js @@ -11,6 +11,11 @@ */ 'use strict'; +/** + * Old (compatibility) renderer. + * Geras: spirit of old age. + * @namespace Blockly.geras.RenderInfo + */ goog.module('Blockly.geras.RenderInfo'); const BaseRenderInfo = goog.require('Blockly.blockRendering.RenderInfo'); @@ -43,6 +48,7 @@ const {BlockSvg} = goog.requireType('Blockly.BlockSvg'); * @constructor * @package * @extends {BaseRenderInfo} + * @alias Blockly.geras.RenderInfo */ const RenderInfo = function(renderer, block) { RenderInfo.superClass_.constructor.call(this, renderer, block); diff --git a/core/renderers/geras/measurables/inline_input.js b/core/renderers/geras/measurables/inline_input.js index ed534cd8d..8367fd274 100644 --- a/core/renderers/geras/measurables/inline_input.js +++ b/core/renderers/geras/measurables/inline_input.js @@ -11,6 +11,11 @@ */ 'use strict'; +/** + * Objects representing inline inputs with connections on a + * rendered block. + * @namespace Blockly.geras.InlineInput + */ goog.module('Blockly.geras.InlineInput'); const BaseInlineInput = goog.require('Blockly.blockRendering.InlineInput'); @@ -31,6 +36,7 @@ const object = goog.require('Blockly.utils.object'); * @package * @constructor * @extends {BaseInlineInput} + * @alias Blockly.geras.InlineInput */ const InlineInput = function(constants, input) { InlineInput.superClass_.constructor.call(this, constants, input); diff --git a/core/renderers/geras/measurables/statement_input.js b/core/renderers/geras/measurables/statement_input.js index 92d58c303..adb950b3c 100644 --- a/core/renderers/geras/measurables/statement_input.js +++ b/core/renderers/geras/measurables/statement_input.js @@ -11,6 +11,11 @@ */ 'use strict'; +/** + * Objects representing statement inputs with connections on a + * rendered block. + * @namespace Blockly.geras.StatementInput + */ goog.module('Blockly.geras.StatementInput'); const BaseStatementInput = goog.require('Blockly.blockRendering.StatementInput'); @@ -31,6 +36,7 @@ const object = goog.require('Blockly.utils.object'); * @package * @constructor * @extends {BaseStatementInput} + * @alias Blockly.geras.StatementInput */ const StatementInput = function(constants, input) { StatementInput.superClass_.constructor.call(this, constants, input); diff --git a/core/renderers/geras/path_object.js b/core/renderers/geras/path_object.js index dc07b707e..4830d01a5 100644 --- a/core/renderers/geras/path_object.js +++ b/core/renderers/geras/path_object.js @@ -11,6 +11,10 @@ 'use strict'; +/** + * An object that owns a block's rendering SVG elements. + * @namespace Blockly.geras.PathObject + */ goog.module('Blockly.geras.PathObject'); const BasePathObject = goog.require('Blockly.blockRendering.PathObject'); @@ -34,6 +38,7 @@ const object = goog.require('Blockly.utils.object'); * @constructor * @extends {BasePathObject} * @package + * @alias Blockly.geras.PathObject */ const PathObject = function(root, style, constants) { /** diff --git a/core/renderers/geras/renderer.js b/core/renderers/geras/renderer.js index b9ee3d6cc..f76140b06 100644 --- a/core/renderers/geras/renderer.js +++ b/core/renderers/geras/renderer.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Geras renderer. + * @namespace Blockly.geras.Renderer + */ goog.module('Blockly.geras.Renderer'); const BaseRenderer = goog.require('Blockly.blockRendering.Renderer'); @@ -36,6 +40,7 @@ const {BlockSvg} = goog.requireType('Blockly.BlockSvg'); * @package * @constructor * @extends {BaseRenderer} + * @alias Blockly.geras.Renderer */ const Renderer = function(name) { Renderer.superClass_.constructor.call(this, name); diff --git a/core/renderers/measurables/base.js b/core/renderers/measurables/base.js index a7d208f3a..45f254833 100644 --- a/core/renderers/measurables/base.js +++ b/core/renderers/measurables/base.js @@ -11,6 +11,10 @@ 'use strict'; +/** + * Methods for graphically rendering a block as SVG. + * @namespace Blockly.blockRendering.Measurable + */ goog.module('Blockly.blockRendering.Measurable'); /* eslint-disable-next-line no-unused-vars */ @@ -26,6 +30,7 @@ const Types = goog.require('Blockly.blockRendering.Types'); * constants provider. * @package * @constructor + * @alias Blockly.blockRendering.Measurable */ const Measurable = function(constants) { this.width = 0; diff --git a/core/renderers/measurables/bottom_row.js b/core/renderers/measurables/bottom_row.js index 6855089c7..5e1bfd807 100644 --- a/core/renderers/measurables/bottom_row.js +++ b/core/renderers/measurables/bottom_row.js @@ -10,6 +10,11 @@ * @author fenichel@google.com (Rachel Fenichel) */ +/** + * Object representing a bottom row on a rendered block. + * of its subcomponents. + * @namespace Blockly.blockRendering.BottomRow + */ goog.module('Blockly.blockRendering.BottomRow'); /* eslint-disable-next-line no-unused-vars */ @@ -33,6 +38,7 @@ const {BlockSvg} = goog.requireType('Blockly.BlockSvg'); * @package * @constructor * @extends {Row} + * @alias Blockly.blockRendering.BottomRow */ const BottomRow = function(constants) { BottomRow.superClass_.constructor.call(this, constants); diff --git a/core/renderers/measurables/connection.js b/core/renderers/measurables/connection.js index 3f608f150..b97e72ff2 100644 --- a/core/renderers/measurables/connection.js +++ b/core/renderers/measurables/connection.js @@ -10,6 +10,11 @@ * @author fenichel@google.com (Rachel Fenichel) */ +/** + * Base class representing the space a connection takes up during + * rendering. + * @namespace Blockly.blockRendering.Connection + */ goog.module('Blockly.blockRendering.Connection'); /* eslint-disable-next-line no-unused-vars */ @@ -31,6 +36,7 @@ const object = goog.require('Blockly.utils.object'); * @package * @constructor * @extends {Measurable} + * @alias Blockly.blockRendering.Connection */ const Connection = function(constants, connectionModel) { Connection.superClass_.constructor.call(this, constants); diff --git a/core/renderers/measurables/external_value_input.js b/core/renderers/measurables/external_value_input.js index 06d48df88..737d61c06 100644 --- a/core/renderers/measurables/external_value_input.js +++ b/core/renderers/measurables/external_value_input.js @@ -10,6 +10,11 @@ * @author fenichel@google.com (Rachel Fenichel) */ +/** + * Class representing external value inputs with connections on a + * rendered block. + * @namespace Blockly.blockRendering.ExternalValueInput + */ goog.module('Blockly.blockRendering.ExternalValueInput'); /* eslint-disable-next-line no-unused-vars */ @@ -31,6 +36,7 @@ const object = goog.require('Blockly.utils.object'); * @package * @constructor * @extends {InputConnection} + * @alias Blockly.blockRendering.ExternalValueInput */ const ExternalValueInput = function(constants, input) { ExternalValueInput.superClass_.constructor.call(this, constants, input); diff --git a/core/renderers/measurables/field.js b/core/renderers/measurables/field.js index 2d224913c..d34df815d 100644 --- a/core/renderers/measurables/field.js +++ b/core/renderers/measurables/field.js @@ -10,6 +10,11 @@ * @author fenichel@google.com (Rachel Fenichel) */ +/** + * Objects representing a field in a row of a rendered + * block. + * @namespace Blockly.blockRendering.Field + */ goog.module('Blockly.blockRendering.Field'); /* eslint-disable-next-line no-unused-vars */ @@ -33,6 +38,7 @@ const object = goog.require('Blockly.utils.object'); * @package * @constructor * @extends {Measurable} + * @alias Blockly.blockRendering.Field */ const Field = function(constants, field, parentInput) { Field.superClass_.constructor.call(this, constants); diff --git a/core/renderers/measurables/hat.js b/core/renderers/measurables/hat.js index 3d6f18e48..288dcc0de 100644 --- a/core/renderers/measurables/hat.js +++ b/core/renderers/measurables/hat.js @@ -10,6 +10,11 @@ * @author fenichel@google.com (Rachel Fenichel) */ +/** + * Objects representing a hat in a row of a rendered + * block. + * @namespace Blockly.blockRendering.Hat + */ goog.module('Blockly.blockRendering.Hat'); /* eslint-disable-next-line no-unused-vars */ @@ -27,6 +32,7 @@ const object = goog.require('Blockly.utils.object'); * @package * @constructor * @extends {Measurable} + * @alias Blockly.blockRendering.Hat */ const Hat = function(constants) { Hat.superClass_.constructor.call(this, constants); diff --git a/core/renderers/measurables/icon.js b/core/renderers/measurables/icon.js index d5b0b5fd4..e023d0cfc 100644 --- a/core/renderers/measurables/icon.js +++ b/core/renderers/measurables/icon.js @@ -10,6 +10,11 @@ * @author fenichel@google.com (Rachel Fenichel) */ +/** + * Objects representing an icon in a row of a rendered + * block. + * @namespace Blockly.blockRendering.Icon + */ goog.module('Blockly.blockRendering.Icon'); /* eslint-disable-next-line no-unused-vars */ @@ -30,6 +35,7 @@ const object = goog.require('Blockly.utils.object'); * @package * @constructor * @extends {Measurable} + * @alias Blockly.blockRendering.Icon */ const Icon = function(constants, icon) { Icon.superClass_.constructor.call(this, constants); diff --git a/core/renderers/measurables/in_row_spacer.js b/core/renderers/measurables/in_row_spacer.js index d8ef7fef0..a8bcc9afb 100644 --- a/core/renderers/measurables/in_row_spacer.js +++ b/core/renderers/measurables/in_row_spacer.js @@ -10,6 +10,11 @@ * @author fenichel@google.com (Rachel Fenichel) */ +/** + * Objects representing a spacer in a row of a rendered + * block. + * @namespace Blockly.blockRendering.InRowSpacer + */ goog.module('Blockly.blockRendering.InRowSpacer'); /* eslint-disable-next-line no-unused-vars */ @@ -28,6 +33,7 @@ const object = goog.require('Blockly.utils.object'); * @package * @constructor * @extends {Measurable} + * @alias Blockly.blockRendering.InRowSpacer */ const InRowSpacer = function(constants, width) { InRowSpacer.superClass_.constructor.call(this, constants); diff --git a/core/renderers/measurables/inline_input.js b/core/renderers/measurables/inline_input.js index d13c498bb..0741684bf 100644 --- a/core/renderers/measurables/inline_input.js +++ b/core/renderers/measurables/inline_input.js @@ -10,6 +10,11 @@ * @author fenichel@google.com (Rachel Fenichel) */ +/** + * Class representing inline inputs with connections on a rendered + * block. + * @namespace Blockly.blockRendering.InlineInput + */ goog.module('Blockly.blockRendering.InlineInput'); /* eslint-disable-next-line no-unused-vars */ @@ -31,6 +36,7 @@ const object = goog.require('Blockly.utils.object'); * @package * @constructor * @extends {InputConnection} + * @alias Blockly.blockRendering.InlineInput */ const InlineInput = function(constants, input) { InlineInput.superClass_.constructor.call(this, constants, input); diff --git a/core/renderers/measurables/input_connection.js b/core/renderers/measurables/input_connection.js index 0466df7c2..3126ccfcf 100644 --- a/core/renderers/measurables/input_connection.js +++ b/core/renderers/measurables/input_connection.js @@ -9,6 +9,10 @@ * @author fenichel@google.com (Rachel Fenichel) */ +/** + * Class representing inputs with connections on a rendered block. + * @namespace Blockly.blockRendering.InputConnection + */ goog.module('Blockly.blockRendering.InputConnection'); const Connection = goog.require('Blockly.blockRendering.Connection'); @@ -29,6 +33,7 @@ const object = goog.require('Blockly.utils.object'); * @package * @constructor * @extends {Connection} + * @alias Blockly.blockRendering.InputConnection */ const InputConnection = function(constants, input) { InputConnection.superClass_.constructor.call( diff --git a/core/renderers/measurables/input_row.js b/core/renderers/measurables/input_row.js index 33c57fa79..338bbf0c6 100644 --- a/core/renderers/measurables/input_row.js +++ b/core/renderers/measurables/input_row.js @@ -10,6 +10,11 @@ * @author fenichel@google.com (Rachel Fenichel) */ +/** + * Object representing a row that holds one or more inputs on a + * rendered block. + * @namespace Blockly.blockRendering.InputRow + */ goog.module('Blockly.blockRendering.InputRow'); /* eslint-disable-next-line no-unused-vars */ @@ -26,6 +31,7 @@ const object = goog.require('Blockly.utils.object'); * @package * @constructor * @extends {Row} + * @alias Blockly.blockRendering.InputRow */ const InputRow = function(constants) { InputRow.superClass_.constructor.call(this, constants); diff --git a/core/renderers/measurables/jagged_edge.js b/core/renderers/measurables/jagged_edge.js index c4e99faba..7f5b0c06a 100644 --- a/core/renderers/measurables/jagged_edge.js +++ b/core/renderers/measurables/jagged_edge.js @@ -10,6 +10,11 @@ * @author fenichel@google.com (Rachel Fenichel) */ +/** + * Objects representing a jagged edge in a row of a rendered + * block. + * @namespace Blockly.blockRendering.JaggedEdge + */ goog.module('Blockly.blockRendering.JaggedEdge'); /* eslint-disable-next-line no-unused-vars */ @@ -27,6 +32,7 @@ const object = goog.require('Blockly.utils.object'); * @package * @constructor * @extends {Measurable} + * @alias Blockly.blockRendering.JaggedEdge */ const JaggedEdge = function(constants) { JaggedEdge.superClass_.constructor.call(this, constants); diff --git a/core/renderers/measurables/next_connection.js b/core/renderers/measurables/next_connection.js index 3414c56a2..ac14fc97a 100644 --- a/core/renderers/measurables/next_connection.js +++ b/core/renderers/measurables/next_connection.js @@ -10,6 +10,11 @@ * @author fenichel@google.com (Rachel Fenichel) */ +/** + * Class representing the space a next connection takes up during + * rendering. + * @namespace Blockly.blockRendering.NextConnection + */ goog.module('Blockly.blockRendering.NextConnection'); const Connection = goog.require('Blockly.blockRendering.Connection'); @@ -31,6 +36,7 @@ const object = goog.require('Blockly.utils.object'); * @package * @constructor * @extends {Connection} + * @alias Blockly.blockRendering.NextConnection */ const NextConnection = function(constants, connectionModel) { NextConnection.superClass_.constructor.call(this, constants, connectionModel); diff --git a/core/renderers/measurables/output_connection.js b/core/renderers/measurables/output_connection.js index a91c309c9..e3ef96396 100644 --- a/core/renderers/measurables/output_connection.js +++ b/core/renderers/measurables/output_connection.js @@ -11,6 +11,11 @@ * @author fenichel@google.com (Rachel Fenichel) */ +/** + * Class representing the space a output connection takes up + * during rendering. + * @namespace Blockly.blockRendering.OutputConnection + */ goog.module('Blockly.blockRendering.OutputConnection'); const Connection = goog.require('Blockly.blockRendering.Connection'); @@ -32,6 +37,7 @@ const object = goog.require('Blockly.utils.object'); * @package * @constructor * @extends {Connection} + * @alias Blockly.blockRendering.OutputConnection */ const OutputConnection = function(constants, connectionModel) { OutputConnection.superClass_.constructor.call( diff --git a/core/renderers/measurables/previous_connection.js b/core/renderers/measurables/previous_connection.js index 4eb2c0f31..02c31fd2f 100644 --- a/core/renderers/measurables/previous_connection.js +++ b/core/renderers/measurables/previous_connection.js @@ -10,6 +10,11 @@ * @author fenichel@google.com (Rachel Fenichel) */ +/** + * Class representing the space a previous connection takes up + * during rendering. + * @namespace Blockly.blockRendering.PreviousConnection + */ goog.module('Blockly.blockRendering.PreviousConnection'); const Connection = goog.require('Blockly.blockRendering.Connection'); @@ -31,6 +36,7 @@ const object = goog.require('Blockly.utils.object'); * @package * @constructor * @extends {Connection} + * @alias Blockly.blockRendering.PreviousConnection */ const PreviousConnection = function(constants, connectionModel) { PreviousConnection.superClass_.constructor.call( diff --git a/core/renderers/measurables/round_corner.js b/core/renderers/measurables/round_corner.js index 8c79a7341..b6d0dcaea 100644 --- a/core/renderers/measurables/round_corner.js +++ b/core/renderers/measurables/round_corner.js @@ -10,6 +10,11 @@ * @author fenichel@google.com (Rachel Fenichel) */ +/** + * Objects representing a round corner in a row of a rendered + * block. + * @namespace Blockly.blockRendering.RoundCorner + */ goog.module('Blockly.blockRendering.RoundCorner'); /* eslint-disable-next-line no-unused-vars */ @@ -28,6 +33,7 @@ const object = goog.require('Blockly.utils.object'); * @package * @constructor * @extends {Measurable} + * @alias Blockly.blockRendering.RoundCorner */ const RoundCorner = function(constants, opt_position) { RoundCorner.superClass_.constructor.call(this, constants); diff --git a/core/renderers/measurables/row.js b/core/renderers/measurables/row.js index c776b1ce9..b81f9a92e 100644 --- a/core/renderers/measurables/row.js +++ b/core/renderers/measurables/row.js @@ -9,6 +9,10 @@ * @author fenichel@google.com (Rachel Fenichel) */ +/** + * Object representing a single row on a rendered block. + * @namespace Blockly.blockRendering.Row + */ goog.module('Blockly.blockRendering.Row'); /* eslint-disable-next-line no-unused-vars */ @@ -29,6 +33,7 @@ const Types = goog.require('Blockly.blockRendering.Types'); * constants provider. * @package * @constructor + * @alias Blockly.blockRendering.Row */ const Row = function(constants) { /** diff --git a/core/renderers/measurables/spacer_row.js b/core/renderers/measurables/spacer_row.js index 8dde265ed..bf0016d12 100644 --- a/core/renderers/measurables/spacer_row.js +++ b/core/renderers/measurables/spacer_row.js @@ -9,6 +9,10 @@ * @author fenichel@google.com (Rachel Fenichel) */ +/** + * Object representing a spacer between two rows. + * @namespace Blockly.blockRendering.SpacerRow + */ goog.module('Blockly.blockRendering.SpacerRow'); /* eslint-disable-next-line no-unused-vars */ @@ -28,6 +32,7 @@ const object = goog.require('Blockly.utils.object'); * @package * @constructor * @extends {Row} + * @alias Blockly.blockRendering.SpacerRow */ const SpacerRow = function(constants, height, width) { SpacerRow.superClass_.constructor.call(this, constants); diff --git a/core/renderers/measurables/square_corner.js b/core/renderers/measurables/square_corner.js index 7674498f9..b38ab6b66 100644 --- a/core/renderers/measurables/square_corner.js +++ b/core/renderers/measurables/square_corner.js @@ -10,6 +10,11 @@ * @author fenichel@google.com (Rachel Fenichel) */ +/** + * Objects representing a square corner in a row of a rendered + * block. + * @namespace Blockly.blockRendering.SquareCorner + */ goog.module('Blockly.blockRendering.SquareCorner'); /* eslint-disable-next-line no-unused-vars */ @@ -28,6 +33,7 @@ const object = goog.require('Blockly.utils.object'); * @package * @constructor * @extends {Measurable} + * @alias Blockly.blockRendering.SquareCorner */ const SquareCorner = function(constants, opt_position) { SquareCorner.superClass_.constructor.call(this, constants); diff --git a/core/renderers/measurables/statement_input.js b/core/renderers/measurables/statement_input.js index d151d0595..5d73f4862 100644 --- a/core/renderers/measurables/statement_input.js +++ b/core/renderers/measurables/statement_input.js @@ -10,6 +10,11 @@ * @author fenichel@google.com (Rachel Fenichel) */ +/** + * Class representing statement inputs with connections on a + * rendered block. + * @namespace Blockly.blockRendering.StatementInput + */ goog.module('Blockly.blockRendering.StatementInput'); /* eslint-disable-next-line no-unused-vars */ @@ -31,6 +36,7 @@ const object = goog.require('Blockly.utils.object'); * @package * @constructor * @extends {InputConnection} + * @alias Blockly.blockRendering.StatementInput */ const StatementInput = function(constants, input) { StatementInput.superClass_.constructor.call(this, constants, input); diff --git a/core/renderers/measurables/top_row.js b/core/renderers/measurables/top_row.js index 569189533..702f2c6ae 100644 --- a/core/renderers/measurables/top_row.js +++ b/core/renderers/measurables/top_row.js @@ -9,6 +9,10 @@ * @author fenichel@google.com (Rachel Fenichel) */ +/** + * Object representing a top row on a rendered block. + * @namespace Blockly.blockRendering.TopRow + */ goog.module('Blockly.blockRendering.TopRow'); /* eslint-disable-next-line no-unused-vars */ @@ -34,6 +38,7 @@ const {BlockSvg} = goog.requireType('Blockly.BlockSvg'); * @package * @constructor * @extends {Row} + * @alias Blockly.blockRendering.TopRow */ const TopRow = function(constants) { TopRow.superClass_.constructor.call(this, constants); diff --git a/core/renderers/measurables/types.js b/core/renderers/measurables/types.js index 6c201f853..d358c9876 100644 --- a/core/renderers/measurables/types.js +++ b/core/renderers/measurables/types.js @@ -11,6 +11,10 @@ 'use strict'; +/** + * Measurable types. + * @namespace Blockly.blockRendering.Types + */ goog.module('Blockly.blockRendering.Types'); /* eslint-disable-next-line no-unused-vars */ @@ -22,6 +26,7 @@ const Row = goog.requireType('Blockly.blockRendering.Row'); /** * Types of rendering elements. * @enum {number} + * @alias Blockly.blockRendering.Types */ const Types = { NONE: 0, // None diff --git a/core/renderers/minimalist/constants.js b/core/renderers/minimalist/constants.js index bbc11be1a..99a71a2fe 100644 --- a/core/renderers/minimalist/constants.js +++ b/core/renderers/minimalist/constants.js @@ -10,6 +10,11 @@ */ 'use strict'; +/** + * An object that provides constants for rendering blocks in the + * minimalist renderer. + * @namespace Blockly.minimalist.ConstantProvider + */ goog.module('Blockly.minimalist.ConstantProvider'); const BaseConstantProvider = goog.require('Blockly.blockRendering.ConstantProvider'); @@ -21,6 +26,7 @@ const object = goog.require('Blockly.utils.object'); * @constructor * @package * @extends {BaseConstantProvider} + * @alias Blockly.minimalist.ConstantProvider */ const ConstantProvider = function() { ConstantProvider.superClass_.constructor.call(this); diff --git a/core/renderers/minimalist/drawer.js b/core/renderers/minimalist/drawer.js index 5cd9fc5fa..1a920eabd 100644 --- a/core/renderers/minimalist/drawer.js +++ b/core/renderers/minimalist/drawer.js @@ -9,6 +9,10 @@ */ 'use strict'; +/** + * Minimalist rendering drawer. + * @namespace Blockly.minimalist.Drawer + */ goog.module('Blockly.minimalist.Drawer'); const BaseDrawer = goog.require('Blockly.blockRendering.Drawer'); @@ -27,6 +31,7 @@ const {BlockSvg} = goog.requireType('Blockly.BlockSvg'); * @package * @constructor * @extends {BaseDrawer} + * @alias Blockly.minimalist.Drawer */ const Drawer = function(block, info) { Drawer.superClass_.constructor.call(this, block, info); diff --git a/core/renderers/minimalist/info.js b/core/renderers/minimalist/info.js index 374600efd..e2adce195 100644 --- a/core/renderers/minimalist/info.js +++ b/core/renderers/minimalist/info.js @@ -9,6 +9,10 @@ */ 'use strict'; +/** + * Minimalist render info object. + * @namespace Blockly.minimalist.RenderInfo + */ goog.module('Blockly.minimalist.RenderInfo'); const BaseRenderInfo = goog.require('Blockly.blockRendering.RenderInfo'); @@ -31,6 +35,7 @@ const {BlockSvg} = goog.requireType('Blockly.BlockSvg'); * @constructor * @package * @extends {BaseRenderInfo} + * @alias Blockly.minimalist.RenderInfo */ const RenderInfo = function(renderer, block) { RenderInfo.superClass_.constructor.call(this, renderer, block); diff --git a/core/renderers/minimalist/minimalist.js b/core/renderers/minimalist/minimalist.js index 9cb9e8bf7..4f1f0124c 100644 --- a/core/renderers/minimalist/minimalist.js +++ b/core/renderers/minimalist/minimalist.js @@ -9,6 +9,10 @@ */ 'use strict'; +/** + * Re-exports of Blockly.minimalist.* modules. + * @namespace Blockly.minimalist + */ goog.module('Blockly.minimalist'); const ConstantProvider = goog.require('Blockly.minimalist.ConstantProvider'); diff --git a/core/renderers/minimalist/renderer.js b/core/renderers/minimalist/renderer.js index b3adf69e4..e878cd810 100644 --- a/core/renderers/minimalist/renderer.js +++ b/core/renderers/minimalist/renderer.js @@ -9,6 +9,10 @@ */ 'use strict'; +/** + * Minimalist renderer. + * @namespace Blockly.minimalist.Renderer + */ goog.module('Blockly.minimalist.Renderer'); /* eslint-disable-next-line no-unused-vars */ @@ -29,6 +33,7 @@ const {BlockSvg} = goog.requireType('Blockly.BlockSvg'); * @package * @constructor * @extends {BaseRenderer} + * @alias Blockly.minimalist.Renderer */ const Renderer = function(name) { Renderer.superClass_.constructor.call(this, name); diff --git a/core/renderers/thrasos/info.js b/core/renderers/thrasos/info.js index b3a924c9a..0d65d4294 100644 --- a/core/renderers/thrasos/info.js +++ b/core/renderers/thrasos/info.js @@ -11,6 +11,11 @@ */ 'use strict'; +/** + * New (evolving) renderer. + * Thrasos: spirit of boldness. + * @namespace Blockly.thrasos.RenderInfo + */ goog.module('Blockly.thrasos.RenderInfo'); const BaseRenderInfo = goog.require('Blockly.blockRendering.RenderInfo'); @@ -37,6 +42,7 @@ const {BlockSvg} = goog.requireType('Blockly.BlockSvg'); * @constructor * @package * @extends {BaseRenderInfo} + * @alias Blockly.thrasos.RenderInfo */ const RenderInfo = function(renderer, block) { RenderInfo.superClass_.constructor.call(this, renderer, block); diff --git a/core/renderers/thrasos/renderer.js b/core/renderers/thrasos/renderer.js index 1d4077d41..650eeb287 100644 --- a/core/renderers/thrasos/renderer.js +++ b/core/renderers/thrasos/renderer.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Thrasos renderer. + * @namespace Blockly.thrasos.Renderer + */ goog.module('Blockly.thrasos.Renderer'); const BaseRenderer = goog.require('Blockly.blockRendering.Renderer'); @@ -26,6 +30,7 @@ const {BlockSvg} = goog.requireType('Blockly.BlockSvg'); * @package * @constructor * @extends {BaseRenderer} + * @alias Blockly.thrasos.Renderer */ const Renderer = function(name) { Renderer.superClass_.constructor.call(this, name); diff --git a/core/renderers/thrasos/thrasos.js b/core/renderers/thrasos/thrasos.js index a5a5bfc45..9bf5e0c60 100644 --- a/core/renderers/thrasos/thrasos.js +++ b/core/renderers/thrasos/thrasos.js @@ -9,6 +9,10 @@ */ 'use strict'; +/** + * Re-exports of Blockly.thrasos.* modules. + * @namespace Blockly.thrasos + */ goog.module('Blockly.thrasos'); const RenderInfo = goog.require('Blockly.thrasos.RenderInfo'); diff --git a/core/renderers/zelos/constants.js b/core/renderers/zelos/constants.js index daa765a3b..1fc6052b3 100644 --- a/core/renderers/zelos/constants.js +++ b/core/renderers/zelos/constants.js @@ -11,6 +11,11 @@ */ 'use strict'; +/** + * An object that provides constants for rendering blocks in Zelos + * mode. + * @namespace Blockly.zelos.ConstantProvider + */ goog.module('Blockly.zelos.ConstantProvider'); const BaseConstantProvider = goog.require('Blockly.blockRendering.ConstantProvider'); @@ -27,6 +32,7 @@ const {ConnectionType} = goog.require('Blockly.ConnectionType'); * @constructor * @package * @extends {BaseConstantProvider} + * @alias Blockly.zelos.ConstantProvider */ const ConstantProvider = function() { ConstantProvider.superClass_.constructor.call(this); diff --git a/core/renderers/zelos/drawer.js b/core/renderers/zelos/drawer.js index 33dff7f0a..d71761f84 100644 --- a/core/renderers/zelos/drawer.js +++ b/core/renderers/zelos/drawer.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Zelos renderer. + * @namespace Blockly.zelos.Drawer + */ goog.module('Blockly.zelos.Drawer'); const BaseDrawer = goog.require('Blockly.blockRendering.Drawer'); @@ -34,6 +38,7 @@ const {BlockSvg} = goog.requireType('Blockly.BlockSvg'); * @package * @constructor * @extends {BaseDrawer} + * @alias Blockly.zelos.Drawer */ const Drawer = function(block, info) { Drawer.superClass_.constructor.call(this, block, info); diff --git a/core/renderers/zelos/info.js b/core/renderers/zelos/info.js index a38bda9cf..84ba84469 100644 --- a/core/renderers/zelos/info.js +++ b/core/renderers/zelos/info.js @@ -11,6 +11,10 @@ */ 'use strict'; +/** + * Makecode/scratch-style renderer. + * @namespace Blockly.zelos.RenderInfo + */ goog.module('Blockly.zelos.RenderInfo'); const BaseRenderInfo = goog.require('Blockly.blockRendering.RenderInfo'); @@ -48,6 +52,7 @@ const {BlockSvg} = goog.requireType('Blockly.BlockSvg'); * @constructor * @package * @extends {BaseRenderInfo} + * @alias Blockly.zelos.RenderInfo */ const RenderInfo = function(renderer, block) { RenderInfo.superClass_.constructor.call(this, renderer, block); diff --git a/core/renderers/zelos/marker_svg.js b/core/renderers/zelos/marker_svg.js index c85a258a7..6ce73bd06 100644 --- a/core/renderers/zelos/marker_svg.js +++ b/core/renderers/zelos/marker_svg.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Methods for graphically rendering a marker as SVG. + * @namespace Blockly.zelos.MarkerSvg + */ goog.module('Blockly.zelos.MarkerSvg'); const BaseMarkerSvg = goog.require('Blockly.blockRendering.MarkerSvg'); @@ -38,6 +42,7 @@ const {Marker} = goog.requireType('Blockly.Marker'); * @param {!Marker} marker The marker to draw. * @constructor * @extends {BaseMarkerSvg} + * @alias Blockly.zelos.MarkerSvg */ const MarkerSvg = function(workspace, constants, marker) { MarkerSvg.superClass_.constructor.call(this, workspace, constants, marker); diff --git a/core/renderers/zelos/measurables/bottom_row.js b/core/renderers/zelos/measurables/bottom_row.js index 0c608af92..61ce68092 100644 --- a/core/renderers/zelos/measurables/bottom_row.js +++ b/core/renderers/zelos/measurables/bottom_row.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * An object representing the bottom row of a rendered block. + * @namespace Blockly.zelos.BottomRow + */ goog.module('Blockly.zelos.BottomRow'); const BaseBottomRow = goog.require('Blockly.blockRendering.BottomRow'); @@ -28,6 +32,7 @@ const object = goog.require('Blockly.utils.object'); * @package * @constructor * @extends {BaseBottomRow} + * @alias Blockly.zelos.BottomRow */ const BottomRow = function(constants) { BottomRow.superClass_.constructor.call(this, constants); diff --git a/core/renderers/zelos/measurables/inputs.js b/core/renderers/zelos/measurables/inputs.js index f412a3484..f3a588bc9 100644 --- a/core/renderers/zelos/measurables/inputs.js +++ b/core/renderers/zelos/measurables/inputs.js @@ -10,6 +10,11 @@ * @author samelh@google.com (Sam El-Husseini) */ +/** + * Zelos specific objects representing inputs with connections on + * a rendered block. + * @namespace Blockly.zelos.StatementInput + */ goog.module('Blockly.zelos.StatementInput'); const BaseStatementInput = goog.require('Blockly.blockRendering.StatementInput'); @@ -29,6 +34,7 @@ const object = goog.require('Blockly.utils.object'); * @package * @constructor * @extends {BaseStatementInput} + * @alias Blockly.zelos.StatementInput */ const StatementInput = function(constants, input) { StatementInput.superClass_.constructor.call(this, constants, input); diff --git a/core/renderers/zelos/measurables/row_elements.js b/core/renderers/zelos/measurables/row_elements.js index 39c58fd65..80ad8ee90 100644 --- a/core/renderers/zelos/measurables/row_elements.js +++ b/core/renderers/zelos/measurables/row_elements.js @@ -10,6 +10,11 @@ * @author samelh@google.com (Sam El-Husseini) */ +/** + * Zelos specific objects representing elements in a row of a + * rendered block. + * @namespace Blockly.zelos.RightConnectionShape + */ goog.module('Blockly.zelos.RightConnectionShape'); /* eslint-disable-next-line no-unused-vars */ @@ -27,6 +32,7 @@ const object = goog.require('Blockly.utils.object'); * @package * @constructor * @extends {Measurable} + * @alias Blockly.zelos.RightConnectionShape */ const RightConnectionShape = function(constants) { RightConnectionShape.superClass_.constructor.call(this, constants); diff --git a/core/renderers/zelos/measurables/top_row.js b/core/renderers/zelos/measurables/top_row.js index 9c9aa0eda..9ca852d61 100644 --- a/core/renderers/zelos/measurables/top_row.js +++ b/core/renderers/zelos/measurables/top_row.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * An object representing the top row of a rendered block. + * @namespace Blockly.zelos.TopRow + */ goog.module('Blockly.zelos.TopRow'); const BaseTopRow = goog.require('Blockly.blockRendering.TopRow'); @@ -30,6 +34,7 @@ const object = goog.require('Blockly.utils.object'); * @package * @constructor * @extends {BaseTopRow} + * @alias Blockly.zelos.TopRow */ const TopRow = function(constants) { TopRow.superClass_.constructor.call(this, constants); diff --git a/core/renderers/zelos/path_object.js b/core/renderers/zelos/path_object.js index d0236cc06..a8248fee3 100644 --- a/core/renderers/zelos/path_object.js +++ b/core/renderers/zelos/path_object.js @@ -11,6 +11,10 @@ 'use strict'; +/** + * An object that owns a block's rendering SVG elements. + * @namespace Blockly.zelos.PathObject + */ goog.module('Blockly.zelos.PathObject'); const BasePathObject = goog.require('Blockly.blockRendering.PathObject'); @@ -33,6 +37,7 @@ const object = goog.require('Blockly.utils.object'); * @constructor * @extends {BasePathObject} * @package + * @alias Blockly.zelos.PathObject */ const PathObject = function(root, style, constants) { PathObject.superClass_.constructor.call(this, root, style, constants); diff --git a/core/renderers/zelos/renderer.js b/core/renderers/zelos/renderer.js index b96f4cdbb..14983c5d0 100644 --- a/core/renderers/zelos/renderer.js +++ b/core/renderers/zelos/renderer.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Zelos renderer. + * @namespace Blockly.zelos.Renderer + */ goog.module('Blockly.zelos.Renderer'); const BaseRenderer = goog.require('Blockly.blockRendering.Renderer'); @@ -40,6 +44,7 @@ const {Marker} = goog.requireType('Blockly.Marker'); * @package * @constructor * @extends {BaseRenderer} + * @alias Blockly.zelos.Renderer */ const Renderer = function(name) { Renderer.superClass_.constructor.call(this, name); diff --git a/core/renderers/zelos/zelos.js b/core/renderers/zelos/zelos.js index 89b3d0db0..b06a07e91 100644 --- a/core/renderers/zelos/zelos.js +++ b/core/renderers/zelos/zelos.js @@ -9,6 +9,10 @@ */ 'use strict'; +/** + * Re-exports of Blockly.zelos.* modules. + * @namespace Blockly.zelos + */ goog.module('Blockly.zelos'); const BottomRow = goog.require('Blockly.zelos.BottomRow'); diff --git a/core/scrollbar.js b/core/scrollbar.js index 8eb521bc2..eadddcfee 100644 --- a/core/scrollbar.js +++ b/core/scrollbar.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Object representing a scrollbar. + * @namespace Blockly.Scrollbar + */ goog.module('Blockly.Scrollbar'); const Touch = goog.require('Blockly.Touch'); @@ -39,6 +43,7 @@ const utils = goog.require('Blockly.utils'); * @param {string=} opt_class A class to be applied to this scrollbar. * @param {number=} opt_margin The margin to apply to this scrollbar. * @constructor + * @alias Blockly.Scrollbar */ const Scrollbar = function( workspace, horizontal, opt_pair, opt_class, opt_margin) { diff --git a/core/scrollbar_pair.js b/core/scrollbar_pair.js index f2754700c..880f7880c 100644 --- a/core/scrollbar_pair.js +++ b/core/scrollbar_pair.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Object representing a pair of scrollbars. + * @namespace Blockly.ScrollbarPair + */ goog.module('Blockly.ScrollbarPair'); /* eslint-disable-next-line no-unused-vars */ @@ -32,6 +36,7 @@ const eventUtils = goog.require('Blockly.Events.utils'); * @param {string=} opt_class A class to be applied to these scrollbars. * @param {number=} opt_margin The margin to apply to these scrollbars. * @constructor + * @alias Blockly.ScrollbarPair */ const ScrollbarPair = function( workspace, addHorizontal, addVertical, opt_class, opt_margin) { diff --git a/core/serialization/blocks.js b/core/serialization/blocks.js index 1f43fb03b..04a5d7c0f 100644 --- a/core/serialization/blocks.js +++ b/core/serialization/blocks.js @@ -6,10 +6,14 @@ /** * @fileoverview Handles serializing blocks to plain JavaScript objects only - * containing state. + * containing state. */ 'use strict'; +/** + * Handles serializing blocks to plain JavaScript objects only containing state. + * @namespace Blockly.serialization.blocks + */ goog.module('Blockly.serialization.blocks'); goog.module.declareLegacyNamespace(); @@ -39,6 +43,7 @@ const {Block} = goog.requireType('Blockly.Block'); * shadow: (!State|undefined), * block: (!State|undefined) * }} + * @alias Blockly.serialization.blocks.ConnectionState */ var ConnectionState; exports.ConnectionState = ConnectionState; @@ -60,6 +65,7 @@ exports.ConnectionState = ConnectionState; * inputs: (!Object|undefined), * next: (!ConnectionState|undefined) * }} + * @alias Blockly.serialization.blocks.State */ var State; exports.State = State; @@ -83,6 +89,7 @@ exports.State = State; * workspace where that state doesn't yet exist. True by default. * @return {?State} 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 */ const save = function( block, @@ -295,6 +302,7 @@ const saveConnection = function(connection, doFullSerialization) { * recordUndo: If true, events triggered by this function will be undo-able * by the user. False by default. * @return {!Block} The block that was just loaded. + * @alias Blockly.serialization.blocks.append */ const append = function(state, workspace, {recordUndo = false} = {}) { return appendInternal(state, workspace, {recordUndo}); @@ -318,6 +326,7 @@ exports.append = append; * recordUndo: If true, events triggered by this function will be undo-able * by the user. False by default. * @return {!Block} The block that was just appended. + * @alias Blockly.serialization.blocks.appendInternal */ const appendInternal = function( state, @@ -628,6 +637,7 @@ const saveBlock = save; /** * Serializer for saving and loading block state. * @implements {ISerializer} + * @alias Blockly.serialization.blocks.BlockSerializer */ class BlockSerializer { constructor() { diff --git a/core/serialization/exceptions.js b/core/serialization/exceptions.js index c776689a8..1e1129f0a 100644 --- a/core/serialization/exceptions.js +++ b/core/serialization/exceptions.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Contains custom errors thrown by the serialization system. + * @namespace Blockly.serialization.exceptions + */ goog.module('Blockly.serialization.exceptions'); goog.module.declareLegacyNamespace(); @@ -18,13 +22,16 @@ const {State} = goog.requireType('Blockly.serialization.blocks'); /* eslint-disable-next-line no-unused-vars */ const {Block} = goog.requireType('Blockly.Block'); - +/** + * @alias Blockly.serialization.exceptions.DeserializationError + */ class DeserializationError extends Error {} exports.DeserializationError = DeserializationError; /** * Represents an error where the serialized state is expected to provide a * block type, but it is not provided. + * @alias Blockly.serialization.exceptions.MissingBlockType */ class MissingBlockType extends DeserializationError { /** @@ -46,6 +53,7 @@ exports.MissingBlockType = MissingBlockType; /** * 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 */ class MissingConnection extends DeserializationError { /** @@ -77,6 +85,7 @@ exports.MissingConnection = MissingConnection; /** * Represents an error where deserialization tried to connect two connections * that were not compatible. + * @alias Blockly.serialization.exceptions.BadConnectionCheck */ class BadConnectionCheck extends DeserializationError { /** @@ -113,6 +122,7 @@ exports.BadConnectionCheck = BadConnectionCheck; * 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 */ class RealChildOfShadow extends DeserializationError { /** diff --git a/core/serialization/priorities.js b/core/serialization/priorities.js index 66efb03fd..914c66402 100644 --- a/core/serialization/priorities.js +++ b/core/serialization/priorities.js @@ -5,14 +5,17 @@ */ /** - * @fileoverview Includes constants for the priorities of different plugin - * serializers. Higher priorities are deserialized first. + * @fileoverview The top level namespace for priorities of plugin serializers. + * Includes constants for the priorities of different plugin + * serializers. Higher priorities are deserialized first. */ 'use strict'; /** * 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 */ goog.module('Blockly.serialization.priorities'); diff --git a/core/serialization/registry.js b/core/serialization/registry.js index 7806db29f..671236fb0 100644 --- a/core/serialization/registry.js +++ b/core/serialization/registry.js @@ -6,10 +6,15 @@ /** * @fileoverview Contains functions registering serializers (eg blocks, - * variables, plugins, etc). + * variables, plugins, etc). */ 'use strict'; +/** + * Contains functions registering serializers (eg blocks, variables, plugins, + * etc). + * @namespace Blockly.serialization.registry + */ goog.module('Blockly.serialization.registry'); goog.module.declareLegacyNamespace(); @@ -24,6 +29,7 @@ const registry = goog.require('Blockly.registry'); * deserialization. * @param {string} name The name of the serializer to register. * @param {ISerializer} serializer The serializer to register. + * @alias Blockly.serialization.registry.register */ const register = function(name, serializer) { registry.register(registry.Type.SERIALIZER, name, serializer); @@ -33,6 +39,7 @@ exports.register = register; /** * Unregisters the serializer associated with the given name. * @param {string} name The name of the serializer to unregister. + * @alias Blockly.serialization.registry.unregister */ const unregister = function(name) { registry.unregister(registry.Type.SERIALIZER, name); diff --git a/core/serialization/variables.js b/core/serialization/variables.js index c1ae6dc60..7a809be45 100644 --- a/core/serialization/variables.js +++ b/core/serialization/variables.js @@ -6,10 +6,15 @@ /** * @fileoverview Handles serializing variables to plain JavaScript objects, only - * containing state. + * containing state. */ 'use strict'; +/** + * Handles serializing variables to plain JavaScript objects, only containing + * state. + * @namespace Blockly.serialization.variables + */ goog.module('Blockly.serialization.variables'); goog.module.declareLegacyNamespace(); @@ -28,6 +33,7 @@ const serializationRegistry = goog.require('Blockly.serialization.registry'); * id: string, * type: (string|undefined) * }} + * @alias Blockly.serialization.variables.State */ var State; exports.State = State; @@ -35,6 +41,7 @@ exports.State = State; /** * Serializer for saving and loading variable state. * @implements {ISerializer} + * @alias Blockly.serialization.variables.VariableSerializer */ class VariableSerializer { constructor() { diff --git a/core/serialization/workspaces.js b/core/serialization/workspaces.js index 25598116e..be9772563 100644 --- a/core/serialization/workspaces.js +++ b/core/serialization/workspaces.js @@ -6,10 +6,15 @@ /** * @fileoverview Contains top-level functions for serializing workspaces to - * plain JavaScript objects. + * plain JavaScript objects. */ 'use strict'; +/** + * Contains top-level functions for serializing workspaces to plain JavaScript + * objects. + * @namespace Blockly.serialization.workspaces + */ goog.module('Blockly.serialization.workspaces'); goog.module.declareLegacyNamespace(); @@ -24,6 +29,7 @@ const registry = goog.require('Blockly.registry'); * Returns the state of the workspace as a plain JavaScript object. * @param {!Workspace} workspace The workspace to serialize. * @return {!Object} The serialized state of the workspace. + * @alias Blockly.serialization.workspaces.save */ const save = function(workspace) { const state = Object.create(null); @@ -46,6 +52,7 @@ exports.save = save; * @param {{recordUndo: (boolean|undefined)}=} param1 * recordUndo: If true, events triggered by this function will be undo-able * by the user. False by default. + * @alias Blockly.serialization.workspaces.load */ const load = function(state, workspace, {recordUndo = false} = {}) { const serializerMap = registry.getAllItems(registry.Type.SERIALIZER, true); diff --git a/core/shortcut_items.js b/core/shortcut_items.js index 41cbc85a7..bd9e80d9c 100644 --- a/core/shortcut_items.js +++ b/core/shortcut_items.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Registers default keyboard shortcuts. + * @namespace Blockly.ShortcutItems + */ goog.module('Blockly.ShortcutItems'); const Gesture = goog.require('Blockly.Gesture'); @@ -26,6 +30,7 @@ const {BlockSvg} = goog.requireType('Blockly.BlockSvg'); /** * Object holding the names of the default shortcut items. * @enum {string} + * @alias Blockly.ShortcutItems.names */ const names = { ESCAPE: 'escape', @@ -38,7 +43,10 @@ const names = { }; exports.names = names; -/** Keyboard shortcut to hide chaff on escape. */ +/** + * Keyboard shortcut to hide chaff on escape. + * @alias Blockly.ShortcutItems.registerEscape + */ const registerEscape = function() { /** @type {!ShortcutRegistry.KeyboardShortcut} */ const escapeAction = { @@ -56,7 +64,10 @@ const registerEscape = function() { }; exports.registerEscape = registerEscape; -/** Keyboard shortcut to delete a block on delete or backspace */ +/** + * Keyboard shortcut to delete a block on delete or backspace + * @alias Blockly.ShortcutItems.registerDelete + */ const registerDelete = function() { /** @type {!ShortcutRegistry.KeyboardShortcut} */ const deleteShortcut = { @@ -86,7 +97,10 @@ const registerDelete = function() { }; exports.registerDelete = registerDelete; -/** Keyboard shortcut to copy a block on ctrl+c, cmd+c, or alt+c. */ +/** + * Keyboard shortcut to copy a block on ctrl+c, cmd+c, or alt+c. + * @alias Blockly.ShortcutItems.registerCopy + */ const registerCopy = function() { /** @type {!ShortcutRegistry.KeyboardShortcut} */ const copyShortcut = { @@ -121,7 +135,10 @@ const registerCopy = function() { }; exports.registerCopy = registerCopy; -/** Keyboard shortcut to copy and delete a block on ctrl+x, cmd+x, or alt+x. */ +/** + * Keyboard shortcut to copy and delete a block on ctrl+x, cmd+x, or alt+x. + * @alias Blockly.ShortcutItems.registerCut + */ const registerCut = function() { /** @type {!ShortcutRegistry.KeyboardShortcut} */ const cutShortcut = { @@ -160,7 +177,10 @@ const registerCut = function() { }; exports.registerCut = registerCut; -/** Keyboard shortcut to paste a block on ctrl+v, cmd+v, or alt+v. */ +/** + * Keyboard shortcut to paste a block on ctrl+v, cmd+v, or alt+v. + * @alias Blockly.ShortcutItems.registerPaste + */ const registerPaste = function() { /** @type {!ShortcutRegistry.KeyboardShortcut} */ const pasteShortcut = { @@ -189,7 +209,10 @@ const registerPaste = function() { }; exports.registerPaste = registerPaste; -/** Keyboard shortcut to undo the previous action on ctrl+z, cmd+z, or alt+z. */ +/** + * Keyboard shortcut to undo the previous action on ctrl+z, cmd+z, or alt+z. + * @alias Blockly.ShortcutItems.registerUndo + */ const registerUndo = function() { /** @type {!ShortcutRegistry.KeyboardShortcut} */ const undoShortcut = { @@ -223,6 +246,7 @@ exports.registerUndo = registerUndo; /** * Keyboard shortcut to redo the previous action on ctrl+shift+z, cmd+shift+z, * or alt+shift+z. + * @alias Blockly.ShortcutItems.registerRedo */ const registerRedo = function() { /** @type {!ShortcutRegistry.KeyboardShortcut} */ @@ -262,6 +286,7 @@ exports.registerRedo = registerRedo; /** * Registers all default keyboard shortcut item. This should be called once per * instance of KeyboardShortcutRegistry. + * @alias Blockly.ShortcutItems.registerDefaultShortcuts */ const registerDefaultShortcuts = function() { registerEscape(); diff --git a/core/shortcut_registry.js b/core/shortcut_registry.js index d72a2c46c..50008ea8f 100644 --- a/core/shortcut_registry.js +++ b/core/shortcut_registry.js @@ -11,6 +11,11 @@ */ 'use strict'; +/** + * The namespace used to keep track of keyboard shortcuts and the + * key codes used to execute those shortcuts. + * @namespace Blockly.ShortcutRegistry + */ goog.module('Blockly.ShortcutRegistry'); const KeyCodes = goog.require('Blockly.utils.KeyCodes'); @@ -24,6 +29,7 @@ const object = goog.require('Blockly.utils.object'); * singleton. You should not create a new instance, and only access this class * from ShortcutRegistry.registry. * @constructor + * @alias Blockly.ShortcutRegistry */ const ShortcutRegistry = function() { // Singleton instance should be registered once. diff --git a/core/theme.js b/core/theme.js index ce3b02e6d..f8d3d3a65 100644 --- a/core/theme.js +++ b/core/theme.js @@ -9,6 +9,10 @@ */ 'use strict'; +/** + * The class representing a theme. + * @namespace Blockly.Theme + */ goog.module('Blockly.Theme'); const object = goog.require('Blockly.utils.object'); @@ -26,6 +30,7 @@ const registry = goog.require('Blockly.registry'); * @param {!Theme.ComponentStyle=} opt_componentStyles A map of Blockly * component names to style value. * @constructor + * @alias Blockly.Theme */ const Theme = function( name, opt_blockStyles, opt_categoryStyles, opt_componentStyles) { diff --git a/core/theme/classic.js b/core/theme/classic.js index 300a7579f..e88a6f25d 100644 --- a/core/theme/classic.js +++ b/core/theme/classic.js @@ -10,6 +10,11 @@ */ 'use strict'; +/** + * Classic theme. + * Contains multi-coloured border to create shadow effect. + * @namespace Blockly.Themes.Classic + */ goog.module('Blockly.Themes.Classic'); const Theme = goog.require('Blockly.Theme'); diff --git a/core/theme/themes.js b/core/theme/themes.js index 37ca9e01c..e6cac55be 100644 --- a/core/theme/themes.js +++ b/core/theme/themes.js @@ -9,6 +9,10 @@ */ 'use strict'; +/** + * Namespace for themes. + * @namespace Blockly.Themes + */ goog.module('Blockly.Themes'); const Classic = goog.require('Blockly.Themes.Classic'); diff --git a/core/theme/zelos.js b/core/theme/zelos.js index 4d97f4871..5b87e23ef 100644 --- a/core/theme/zelos.js +++ b/core/theme/zelos.js @@ -9,6 +9,10 @@ */ 'use strict'; +/** + * Zelos theme. + * @namespace Blockly.Themes.Zelos + */ goog.module('Blockly.Themes.Zelos'); const Theme = goog.require('Blockly.Theme'); diff --git a/core/theme_manager.js b/core/theme_manager.js index 4e95b0d9f..739b26c22 100644 --- a/core/theme_manager.js +++ b/core/theme_manager.js @@ -12,6 +12,11 @@ */ 'use strict'; +/** + * Object in charge of storing and updating a workspace theme + * and UI components. + * @namespace Blockly.ThemeManager + */ goog.module('Blockly.ThemeManager'); /* eslint-disable-next-line no-unused-vars */ @@ -30,6 +35,7 @@ const utils = goog.require('Blockly.utils'); * @param {!Theme} theme The workspace theme. * @constructor * @package + * @alias Blockly.ThemeManager */ const ThemeManager = function(workspace, theme) { /** diff --git a/core/toolbox/category.js b/core/toolbox/category.js index 1d0a1fe7f..cf0bd52af 100644 --- a/core/toolbox/category.js +++ b/core/toolbox/category.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * A toolbox category used to organize blocks in the toolbox. + * @namespace Blockly.ToolboxCategory + */ goog.module('Blockly.ToolboxCategory'); const Css = goog.require('Blockly.Css'); @@ -39,6 +43,7 @@ const utils = goog.require('Blockly.utils'); * @constructor * @extends {ToolboxItem} * @implements {ISelectableToolboxItem} + * @alias Blockly.ToolboxCategory */ const ToolboxCategory = function(categoryDef, toolbox, opt_parent) { ToolboxCategory.superClass_.constructor.call( diff --git a/core/toolbox/collapsible_category.js b/core/toolbox/collapsible_category.js index e36a6e61c..37ec63a60 100644 --- a/core/toolbox/collapsible_category.js +++ b/core/toolbox/collapsible_category.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * A toolbox category used to organize blocks in the toolbox. + * @namespace Blockly.CollapsibleToolboxCategory + */ goog.module('Blockly.CollapsibleToolboxCategory'); /* eslint-disable-next-line no-unused-vars */ @@ -37,6 +41,7 @@ const toolbox = goog.require('Blockly.utils.toolbox'); * @constructor * @extends {ToolboxCategory} * @implements {ICollapsibleToolboxItem} + * @alias Blockly.CollapsibleToolboxCategory */ const CollapsibleToolboxCategory = function(categoryDef, toolbox, opt_parent) { /** diff --git a/core/toolbox/separator.js b/core/toolbox/separator.js index 359b0cdf3..92f63438b 100644 --- a/core/toolbox/separator.js +++ b/core/toolbox/separator.js @@ -11,6 +11,10 @@ */ 'use strict'; +/** + * A separator used for separating toolbox categories. + * @namespace Blockly.ToolboxSeparator + */ goog.module('Blockly.ToolboxSeparator'); const Css = goog.require('Blockly.Css'); @@ -32,6 +36,7 @@ const toolbox = goog.requireType('Blockly.utils.toolbox'); * @param {!IToolbox} toolbox The parent toolbox for the separator. * @constructor * @extends {ToolboxItem} + * @alias Blockly.ToolboxSeparator */ const ToolboxSeparator = function(separatorDef, toolbox) { ToolboxSeparator.superClass_.constructor.call(this, separatorDef, toolbox); diff --git a/core/toolbox/toolbox.js b/core/toolbox/toolbox.js index 9062766a7..713d15936 100644 --- a/core/toolbox/toolbox.js +++ b/core/toolbox/toolbox.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Toolbox from whence to create blocks. + * @namespace Blockly.Toolbox + */ goog.module('Blockly.Toolbox'); /* eslint-disable-next-line no-unused-vars */ @@ -68,6 +72,7 @@ goog.require('Blockly.Events.ToolboxItemSelect'); * @implements {IStyleable} * @implements {IToolbox} * @extends {DeleteArea} + * @alias Blockly.Toolbox */ const Toolbox = function(workspace) { Toolbox.superClass_.constructor.call(this); diff --git a/core/toolbox/toolbox_item.js b/core/toolbox/toolbox_item.js index dbc380b0f..02ca46b21 100644 --- a/core/toolbox/toolbox_item.js +++ b/core/toolbox/toolbox_item.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * An item in the toolbox. + * @namespace Blockly.ToolboxItem + */ goog.module('Blockly.ToolboxItem'); /* eslint-disable-next-line no-unused-vars */ @@ -34,6 +38,7 @@ const toolbox = goog.requireType('Blockly.utils.toolbox'); * or null if the category does not have a parent. * @constructor * @implements {IToolboxItem} + * @alias Blockly.ToolboxItem */ const ToolboxItem = function(toolboxItemDef, toolbox, opt_parent) { /** diff --git a/core/tooltip.js b/core/tooltip.js index 6686c6e6d..595a5b376 100644 --- a/core/tooltip.js +++ b/core/tooltip.js @@ -16,8 +16,13 @@ 'use strict'; /** - * @name Blockly.Tooltip - * @namespace + * Library to create tooltips for Blockly. + * First, call init() after onload. + * Second, set the 'tooltip' property on any SVG element that needs a tooltip. + * If the tooltip is a string, then 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 */ goog.module('Blockly.Tooltip'); diff --git a/core/touch.js b/core/touch.js index ce2b51b2b..02accca07 100644 --- a/core/touch.js +++ b/core/touch.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Touch handling for Blockly. + * @namespace Blockly.Touch + */ goog.module('Blockly.Touch'); /* eslint-disable-next-line no-unused-vars */ @@ -44,6 +48,7 @@ let touchIdentifier_ = null; * The TOUCH_MAP lookup dictionary specifies additional touch events to fire, * in conjunction with mouse events. * @type {Object} + * @alias Blockly.Touch.TOUCH_MAP */ let TOUCH_MAP = {}; if (globalThis['PointerEvent']) { @@ -80,6 +85,7 @@ let longPid_ = 0; * if the touch event terminates early. * @param {!Event} e Touch start event. * @param {Gesture} gesture The gesture that triggered this longStart. + * @alias Blockly.Touch.longStart */ const longStart = function(e, gesture) { longStop(); @@ -109,6 +115,7 @@ exports.longStart = longStart; /** * 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 */ const longStop = function() { if (longPid_) { @@ -123,6 +130,7 @@ exports.longStop = 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 */ const clearTouchIdentifier = function() { touchIdentifier_ = null; @@ -136,6 +144,7 @@ exports.clearTouchIdentifier = clearTouchIdentifier; * @param {!Event} e The event to check. * @return {boolean} True if this event should be passed through to the * registered handler; false if it should be blocked. + * @alias Blockly.Touch.shouldHandleEvent */ const shouldHandleEvent = function(e) { return !isMouseOrTouchEvent(e) || checkTouchIdentifier(e); @@ -148,6 +157,7 @@ exports.shouldHandleEvent = shouldHandleEvent; * @param {!Event} e Mouse event or touch event. * @return {string} The touch identifier from the first changed touch, if * defined. Otherwise 'mouse'. + * @alias Blockly.Touch.getTouchIdentifierFromEvent */ const getTouchIdentifierFromEvent = function(e) { return e.pointerId != undefined ? @@ -171,6 +181,7 @@ exports.getTouchIdentifierFromEvent = getTouchIdentifierFromEvent; * @param {!Event} e Mouse event or touch event. * @return {boolean} Whether the identifier on the event matches the current * saved identifier. + * @alias Blockly.Touch.checkTouchIdentifier */ const checkTouchIdentifier = function(e) { const identifier = getTouchIdentifierFromEvent(e); @@ -200,6 +211,7 @@ exports.checkTouchIdentifier = checkTouchIdentifier; * 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 {!Event} e A touch event. + * @alias Blockly.Touch.setClientFromTouch */ const setClientFromTouch = function(e) { if (utilsString.startsWith(e.type, 'touch')) { @@ -215,6 +227,7 @@ exports.setClientFromTouch = setClientFromTouch; * Check whether a given event is a mouse or touch event. * @param {!Event} e An event. * @return {boolean} True if it is a mouse or touch event; false otherwise. + * @alias Blockly.Touch.isMouseOrTouchEvent */ const isMouseOrTouchEvent = function(e) { return utilsString.startsWith(e.type, 'touch') || @@ -227,6 +240,7 @@ exports.isMouseOrTouchEvent = isMouseOrTouchEvent; * Check whether a given event is a touch event or a pointer event. * @param {!Event} e An event. * @return {boolean} True if it is a touch event; false otherwise. + * @alias Blockly.Touch.isTouchEvent */ const isTouchEvent = function(e) { return utilsString.startsWith(e.type, 'touch') || @@ -241,6 +255,7 @@ exports.isTouchEvent = isTouchEvent; * touches. * @return {!Array} An array of mouse or touch events. Each touch * event will have exactly one changed touch. + * @alias Blockly.Touch.splitEventByTouches */ const splitEventByTouches = function(e) { const events = []; diff --git a/core/touch_gesture.js b/core/touch_gesture.js index f7b89ff60..8e7f995fd 100644 --- a/core/touch_gesture.js +++ b/core/touch_gesture.js @@ -11,6 +11,11 @@ */ 'use strict'; +/** + * The class extends Gesture to support pinch to zoom + * for both pointer and touch events. + * @namespace Blockly.TouchGesture + */ goog.module('Blockly.TouchGesture'); const Coordinate = goog.require('Blockly.utils.Coordinate'); @@ -34,6 +39,7 @@ const object = goog.require('Blockly.utils.object'); * this gesture and has a reference to it. * @extends {Gesture} * @constructor + * @alias Blockly.TouchGesture */ const TouchGesture = function(e, creatorWorkspace) { TouchGesture.superClass_.constructor.call(this, e, creatorWorkspace); diff --git a/core/trashcan.js b/core/trashcan.js index 36c59edbc..915c7a001 100644 --- a/core/trashcan.js +++ b/core/trashcan.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Object representing a trash can icon. + * @namespace Blockly.Trashcan + */ goog.module('Blockly.Trashcan'); /* eslint-disable-next-line no-unused-vars */ @@ -55,6 +59,7 @@ goog.require('Blockly.Events.TrashcanOpen'); * @implements {IAutoHideable} * @implements {IPositionable} * @extends {DeleteArea} + * @alias Blockly.Trashcan */ const Trashcan = function(workspace) { Trashcan.superClass_.constructor.call(this); diff --git a/core/utils.js b/core/utils.js index 594b3ddff..7f011b0ab 100644 --- a/core/utils.js +++ b/core/utils.js @@ -13,8 +13,10 @@ 'use strict'; /** - * @name Blockly.utils - * @namespace + * Utility methods. + * These methods are not specific to Blockly, and could be factored out into + * a JavaScript framework such as Closure. + * @namespace Blockly.utils */ goog.module('Blockly.utils'); diff --git a/core/utils/aria.js b/core/utils/aria.js index 583f51786..87817c16c 100644 --- a/core/utils/aria.js +++ b/core/utils/aria.js @@ -13,8 +13,10 @@ 'use strict'; /** - * @name Blockly.utils.aria - * @namespace + * 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 */ goog.module('Blockly.utils.aria'); diff --git a/core/utils/colour.js b/core/utils/colour.js index b12690316..7c56601f4 100644 --- a/core/utils/colour.js +++ b/core/utils/colour.js @@ -13,8 +13,10 @@ 'use strict'; /** - * @name Blockly.utils.colour - * @namespace + * Utility methods for colour manipulation. + * These methods are not specific to Blockly, and could be factored out into + * a JavaScript framework such as Closure. + * @namespace Blockly.utils.colour */ goog.module('Blockly.utils.colour'); diff --git a/core/utils/coordinate.js b/core/utils/coordinate.js index 4376fa83d..5e5f979cc 100644 --- a/core/utils/coordinate.js +++ b/core/utils/coordinate.js @@ -13,8 +13,10 @@ 'use strict'; /** - * @name Blockly.utils.Coordinate - * @namespace + * Utility methods for coordinate manipulation. + * These methods are not specific to Blockly, and could be factored out into + * a JavaScript framework such as Closure. + * @namespace Blockly.utils.Coordinate */ goog.module('Blockly.utils.Coordinate'); @@ -24,6 +26,7 @@ goog.module('Blockly.utils.Coordinate'); * @param {number} y Top. * @struct * @constructor + * @alias Blockly.utils.Coordinate */ const Coordinate = function(x, y) { /** diff --git a/core/utils/deprecation.js b/core/utils/deprecation.js index a6dc9b851..3c10e22bb 100644 --- a/core/utils/deprecation.js +++ b/core/utils/deprecation.js @@ -12,8 +12,9 @@ 'use strict'; /** - * @name Blockly.utils.deprecation - * @namespace + * Helper function for warning developers about deprecations. + * This method is not specific to Blockly. + * @namespace Blockly.utils.deprecation */ goog.module('Blockly.utils.deprecation'); diff --git a/core/utils/dom.js b/core/utils/dom.js index f9e5f409f..a22bbbf77 100644 --- a/core/utils/dom.js +++ b/core/utils/dom.js @@ -13,8 +13,10 @@ 'use strict'; /** - * @name Blockly.utils.dom - * @namespace + * 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 */ goog.module('Blockly.utils.dom'); diff --git a/core/utils/global.js b/core/utils/global.js index b969ad38a..a452b766c 100644 --- a/core/utils/global.js +++ b/core/utils/global.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Provides a reference to the global object. + * @namespace Blockly.utils.global + */ goog.module('Blockly.utils.global'); diff --git a/core/utils/idgenerator.js b/core/utils/idgenerator.js index fcd04abc1..269d2945f 100644 --- a/core/utils/idgenerator.js +++ b/core/utils/idgenerator.js @@ -11,8 +11,8 @@ 'use strict'; /** - * @name Blockly.utils.idGenerator - * @namespace + * Generators for unique IDs. + * @namespace Blockly.utils.idGenerator */ goog.module('Blockly.utils.idGenerator'); @@ -20,6 +20,7 @@ goog.module('Blockly.utils.idGenerator'); /** * Namespace object for internal implementations we want to be able to * stub in tests. + * @ignore */ const internal = {}; exports.TEST_ONLY = internal; diff --git a/core/utils/keycodes.js b/core/utils/keycodes.js index ce7beed29..5e02687a5 100644 --- a/core/utils/keycodes.js +++ b/core/utils/keycodes.js @@ -13,8 +13,10 @@ 'use strict'; /** - * @name Blockly.utils.KeyCodes - * @namespace + * 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 */ goog.module('Blockly.utils.KeyCodes'); diff --git a/core/utils/math.js b/core/utils/math.js index 7140ae893..20a5eb1c4 100644 --- a/core/utils/math.js +++ b/core/utils/math.js @@ -13,8 +13,10 @@ 'use strict'; /** - * @name Blockly.utils.math - * @namespace + * 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 */ goog.module('Blockly.utils.math'); diff --git a/core/utils/metrics.js b/core/utils/metrics.js index 909c5fa39..a7f5961ce 100644 --- a/core/utils/metrics.js +++ b/core/utils/metrics.js @@ -11,14 +11,15 @@ 'use strict'; /** - * @name Blockly.utils.Metrics - * @namespace + * Workspace metrics definitions. + * @namespace Blockly.utils.Metrics */ goog.module('Blockly.utils.Metrics'); /** * @record + * @alias Blockly.utils.Metrics */ const Metrics = function() {}; diff --git a/core/utils/object.js b/core/utils/object.js index 3e1795839..fe23f0b45 100644 --- a/core/utils/object.js +++ b/core/utils/object.js @@ -11,8 +11,8 @@ 'use strict'; /** - * @name Blockly.utils.object - * @namespace + * Utility methods for objects. + * @namespace Blockly.utils.object */ goog.module('Blockly.utils.object'); diff --git a/core/utils/rect.js b/core/utils/rect.js index a77ee3728..63c3e19a7 100644 --- a/core/utils/rect.js +++ b/core/utils/rect.js @@ -13,8 +13,10 @@ 'use strict'; /** - * @name Blockly.utils.Rect - * @namespace + * Utility methods for rectangle manipulation. + * These methods are not specific to Blockly, and could be factored out into + * a JavaScript framework such as Closure. + * @namespace Blockly.utils.Rect */ goog.module('Blockly.utils.Rect'); @@ -27,6 +29,7 @@ goog.module('Blockly.utils.Rect'); * @param {number} right Right. * @struct * @constructor + * @alias Blockly.utils.Rect */ const Rect = function(top, bottom, left, right) { /** @type {number} */ diff --git a/core/utils/size.js b/core/utils/size.js index 11d604125..f5aa4df82 100644 --- a/core/utils/size.js +++ b/core/utils/size.js @@ -13,8 +13,10 @@ 'use strict'; /** - * @name Size - * @namespace + * Utility methods for size calculation. + * These methods are not specific to Blockly, and could be factored out into + * a JavaScript framework such as Closure. + * @namespace Blockly.utils.Size */ goog.module('Blockly.utils.Size'); @@ -25,6 +27,7 @@ goog.module('Blockly.utils.Size'); * @param {number} height Height. * @struct * @constructor + * @alias Blockly.utils.Size */ const Size = function(width, height) { /** diff --git a/core/utils/string.js b/core/utils/string.js index f283b982f..d557cb661 100644 --- a/core/utils/string.js +++ b/core/utils/string.js @@ -13,8 +13,10 @@ 'use strict'; /** - * @name Blockly.utils.string - * @namespace + * 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 */ goog.module('Blockly.utils.string'); diff --git a/core/utils/style.js b/core/utils/style.js index fac432edb..74ea969fe 100644 --- a/core/utils/style.js +++ b/core/utils/style.js @@ -13,8 +13,10 @@ 'use strict'; /** - * @name Blockly.utils.style - * @namespace + * 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 */ goog.module('Blockly.utils.style'); diff --git a/core/utils/svg.js b/core/utils/svg.js index 79b55248e..7896509dd 100644 --- a/core/utils/svg.js +++ b/core/utils/svg.js @@ -12,8 +12,9 @@ 'use strict'; /** - * @name Svg - * @namespace + * Defines the Svg class. Its constants enumerate + * all SVG tag names used by Blockly. + * @namespace Blockly.utils.Svg */ goog.module('Blockly.utils.Svg'); @@ -24,6 +25,7 @@ goog.module('Blockly.utils.Svg'); * @constructor * @template T * @private + * @alias Blockly.utils.Svg */ const Svg = function(tagName) { /** diff --git a/core/utils/svg_paths.js b/core/utils/svg_paths.js index bf4c1b2ca..49666000d 100644 --- a/core/utils/svg_paths.js +++ b/core/utils/svg_paths.js @@ -12,8 +12,8 @@ 'use strict'; /** - * @name Blockly.utils.svgPaths - * @namespace + * Methods for creating parts of SVG path strings. See + * @namespace Blockly.utils.svgPaths */ goog.module('Blockly.utils.svgPaths'); diff --git a/core/utils/toolbox.js b/core/utils/toolbox.js index 0be8b1715..5abf50887 100644 --- a/core/utils/toolbox.js +++ b/core/utils/toolbox.js @@ -11,8 +11,8 @@ 'use strict'; /** - * @name Blockly.utils.toolbox - * @namespace + * Utility functions for the toolbox and flyout. + * @namespace Blockly.utils.toolbox */ goog.module('Blockly.utils.toolbox'); diff --git a/core/utils/useragent.js b/core/utils/useragent.js index ca78461eb..db8017f93 100644 --- a/core/utils/useragent.js +++ b/core/utils/useragent.js @@ -13,8 +13,10 @@ 'use strict'; /** - * @name Blockly.utils.userAgent - * @namespace + * 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 */ goog.module('Blockly.utils.userAgent'); diff --git a/core/utils/xml.js b/core/utils/xml.js index b43ac0930..2099cd125 100644 --- a/core/utils/xml.js +++ b/core/utils/xml.js @@ -13,8 +13,10 @@ 'use strict'; /** - * @name Blockly.utils.xml - * @namespace + * 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 */ goog.module('Blockly.utils.xml'); diff --git a/core/variable_map.js b/core/variable_map.js index d0a69e6c8..29fd548f0 100644 --- a/core/variable_map.js +++ b/core/variable_map.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Object representing a map of variables and their types. + * @namespace Blockly.VariableMap + */ goog.module('Blockly.VariableMap'); const Msg = goog.require('Blockly.Msg'); @@ -36,6 +40,7 @@ goog.require('Blockly.Events.VarRename'); * variables are the type indicated by the key. * @param {!Workspace} workspace The workspace this map belongs to. * @constructor + * @alias Blockly.VariableMap */ const VariableMap = function(workspace) { /** diff --git a/core/variable_model.js b/core/variable_model.js index 150ac98fd..220ae0a45 100644 --- a/core/variable_model.js +++ b/core/variable_model.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Components for the variable model. + * @namespace Blockly.VariableModel + */ goog.module('Blockly.VariableModel'); /* eslint-disable-next-line no-unused-vars */ @@ -33,6 +37,7 @@ goog.require('Blockly.Events.VarCreate'); * a UUID. * @see {Blockly.FieldVariable} * @constructor + * @alias Blockly.VariableModel */ const VariableModel = function(workspace, name, opt_type, opt_id) { /** diff --git a/core/variables.js b/core/variables.js index fe121c3cb..32218d0da 100644 --- a/core/variables.js +++ b/core/variables.js @@ -11,8 +11,8 @@ 'use strict'; /** - * @name Blockly.Variables - * @namespace + * Utility functions for handling variables. + * @namespace Blockly.Variables */ goog.module('Blockly.Variables'); diff --git a/core/variables_dynamic.js b/core/variables_dynamic.js index 051f00774..a18b17ace 100644 --- a/core/variables_dynamic.js +++ b/core/variables_dynamic.js @@ -11,6 +11,11 @@ */ 'use strict'; +/** + * Utility functions for handling typed variables. + * + * @namespace Blockly.VariablesDynamic + */ goog.module('Blockly.VariablesDynamic'); const Msg = goog.require('Blockly.Msg'); @@ -45,6 +50,7 @@ exports.onCreateVariableButtonClick_Colour = onCreateVariableButtonClick_Colour; * variable category. * @param {!Workspace} workspace The workspace containing variables. * @return {!Array} Array of XML elements. + * @alias Blockly.VariablesDynamic.flyoutCategory */ const flyoutCategory = function(workspace) { let xmlList = []; @@ -79,6 +85,7 @@ exports.flyoutCategory = flyoutCategory; * Construct the blocks required by the flyout for the variable category. * @param {!Workspace} workspace The workspace containing variables. * @return {!Array} Array of XML block elements. + * @alias Blockly.VariablesDynamic.flyoutCategoryBlocks */ const flyoutCategoryBlocks = function(workspace) { const variableModelList = workspace.getAllVariables(); diff --git a/core/warning.js b/core/warning.js index b3495e2b7..337916b70 100644 --- a/core/warning.js +++ b/core/warning.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Object representing a warning. + * @namespace Blockly.Warning + */ goog.module('Blockly.Warning'); const Bubble = goog.require('Blockly.Bubble'); @@ -33,6 +37,7 @@ goog.require('Blockly.Events.BubbleOpen'); * @param {!Block} block The block associated with this warning. * @extends {Icon} * @constructor + * @alias Blockly.Warning */ const Warning = function(block) { Warning.superClass_.constructor.call(this, block); diff --git a/core/widgetdiv.js b/core/widgetdiv.js index 0b1f58193..5f7a58711 100644 --- a/core/widgetdiv.js +++ b/core/widgetdiv.js @@ -13,8 +13,10 @@ 'use strict'; /** - * @name Blockly.WidgetDiv - * @namespace + * 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 */ goog.module('Blockly.WidgetDiv'); @@ -73,6 +75,8 @@ exports.getDiv = getDiv; /** * Allows unit tests to reset the div. * @param {?Element} newDiv The new value for the DIV field. + * @alias Blockly.WidgetDiv.testOnly_setDiv + * @ignore */ const testOnly_setDiv = function(newDiv) { DIV = newDiv; diff --git a/core/workspace.js b/core/workspace.js index 5a739761a..1fa546c1d 100644 --- a/core/workspace.js +++ b/core/workspace.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Object representing a workspace. + * @namespace Blockly.Workspace + */ goog.module('Blockly.Workspace'); /* eslint-disable-next-line no-unused-vars */ @@ -53,6 +57,7 @@ const WorkspaceDB_ = Object.create(null); * @param {!Options=} opt_options Dictionary of options. * @constructor * @implements {IASTNodeLocation} + * @alias Blockly.Workspace */ const Workspace = function(opt_options) { /** @type {string} */ diff --git a/core/workspace_audio.js b/core/workspace_audio.js index 94c5bd06d..6de9b6f68 100644 --- a/core/workspace_audio.js +++ b/core/workspace_audio.js @@ -11,6 +11,11 @@ */ 'use strict'; +/** + * Object in charge of loading, storing, and playing audio for a + * workspace. + * @namespace Blockly.WorkspaceAudio + */ goog.module('Blockly.WorkspaceAudio'); /* eslint-disable-next-line no-unused-vars */ @@ -25,6 +30,7 @@ const userAgent = goog.require('Blockly.utils.userAgent'); * @param {WorkspaceSvg} parentWorkspace The parent of the workspace * this audio object belongs to, or null. * @constructor + * @alias Blockly.WorkspaceAudio */ const WorkspaceAudio = function(parentWorkspace) { /** diff --git a/core/workspace_comment.js b/core/workspace_comment.js index 362132bd8..67811b508 100644 --- a/core/workspace_comment.js +++ b/core/workspace_comment.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Object representing a code comment on the workspace. + * @namespace Blockly.WorkspaceComment + */ goog.module('Blockly.WorkspaceComment'); const Coordinate = goog.require('Blockly.utils.Coordinate'); @@ -37,6 +41,7 @@ goog.require('Blockly.Events.CommentMove'); * @param {string=} opt_id Optional ID. Use this ID if provided, otherwise * create a new ID. * @constructor + * @alias Blockly.WorkspaceComment */ const WorkspaceComment = function(workspace, content, height, width, opt_id) { /** @type {string} */ diff --git a/core/workspace_comment_svg.js b/core/workspace_comment_svg.js index d21820c1f..9c5d1869d 100644 --- a/core/workspace_comment_svg.js +++ b/core/workspace_comment_svg.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Object representing a code comment on a rendered workspace. + * @namespace Blockly.WorkspaceCommentSvg + */ goog.module('Blockly.WorkspaceCommentSvg'); const ContextMenu = goog.require('Blockly.ContextMenu'); @@ -79,6 +83,7 @@ const TEXTAREA_OFFSET = 2; * @implements {IBubble} * @implements {ICopyable} * @constructor + * @alias Blockly.WorkspaceCommentSvg */ const WorkspaceCommentSvg = function( workspace, content, height, width, opt_id) { diff --git a/core/workspace_drag_surface_svg.js b/core/workspace_drag_surface_svg.js index 5b12d4a68..8e6f772ca 100644 --- a/core/workspace_drag_surface_svg.js +++ b/core/workspace_drag_surface_svg.js @@ -14,6 +14,13 @@ 'use strict'; +/** + * An SVG that floats on top of the workspace. + * 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. + * @namespace Blockly.WorkspaceDragSurfaceSvg + */ goog.module('Blockly.WorkspaceDragSurfaceSvg'); /* eslint-disable-next-line no-unused-vars */ @@ -29,6 +36,7 @@ const utils = goog.require('Blockly.utils'); * blocks are never repainted during drag improving performance. * @param {!Element} container Containing element. * @constructor + * @alias Blockly.WorkspaceDragSurfaceSvg */ const WorkspaceDragSurfaceSvg = function(container) { this.container_ = container; diff --git a/core/workspace_dragger.js b/core/workspace_dragger.js index 92e3f0060..dacb28cf7 100644 --- a/core/workspace_dragger.js +++ b/core/workspace_dragger.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Methods for dragging a workspace visually. + * @namespace Blockly.WorkspaceDragger + */ goog.module('Blockly.WorkspaceDragger'); const Coordinate = goog.require('Blockly.utils.Coordinate'); @@ -26,6 +30,7 @@ const common = goog.require('Blockly.common'); * commands based on events. * @param {!WorkspaceSvg} workspace The workspace to drag. * @constructor + * @alias Blockly.WorkspaceDragger */ const WorkspaceDragger = function(workspace) { /** diff --git a/core/workspace_svg.js b/core/workspace_svg.js index c56602a33..d3c01b95d 100644 --- a/core/workspace_svg.js +++ b/core/workspace_svg.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Object representing a workspace rendered as SVG. + * @namespace Blockly.WorkspaceSvg + */ goog.module('Blockly.WorkspaceSvg'); /* eslint-disable-next-line no-unused-vars */ @@ -119,6 +123,7 @@ goog.require('Blockly.Msg'); * @extends {Workspace} * @implements {IASTNodeLocationSvg} * @constructor + * @alias Blockly.WorkspaceSvg */ const WorkspaceSvg = function( options, opt_blockDragSurface, opt_wsDragSurface) { diff --git a/core/xml.js b/core/xml.js index b5c25d06e..187550e0d 100644 --- a/core/xml.js +++ b/core/xml.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * XML reader and writer. + * @namespace Blockly.Xml + */ goog.module('Blockly.Xml'); /* eslint-disable-next-line no-unused-vars */ @@ -40,6 +44,7 @@ goog.requireType('Blockly.WorkspaceCommentSvg'); * @param {!Workspace} workspace The workspace containing blocks. * @param {boolean=} opt_noId True if the encoder should skip the block IDs. * @return {!Element} XML DOM element. + * @alias Blockly.Xml.workspaceToDom */ const workspaceToDom = function(workspace, opt_noId) { const treeXml = utilsXml.createElement('xml'); @@ -67,6 +72,7 @@ exports.workspaceToDom = workspaceToDom; * @param {!Array} variableList List of all variable * models. * @return {!Element} Tree of XML elements. + * @alias Blockly.Xml.variablesToDom */ const variablesToDom = function(variableList) { const variables = utilsXml.createElement('variables'); @@ -90,6 +96,7 @@ exports.variablesToDom = variablesToDom; * @param {boolean=} opt_noId True if the encoder should skip the block ID. * @return {!Element|!DocumentFragment} Tree of XML elements or an empty * document fragment if the block was an insertion marker. + * @alias Blockly.Xml.blockToDomWithXY */ const blockToDomWithXY = function(block, opt_noId) { if (block.isInsertionMarker()) { // Skip over insertion markers. @@ -155,6 +162,7 @@ const allFieldsToDom = function(block, element) { * @param {boolean=} opt_noId True if the encoder should skip the block ID. * @return {!Element|!DocumentFragment} Tree of XML elements or an empty * document fragment if the block was an insertion marker. + * @alias Blockly.Xml.blockToDom */ const blockToDom = function(block, opt_noId) { // Skip over insertion markers. @@ -323,6 +331,7 @@ const cloneShadow = function(shadow, opt_noId) { * unless the DOM itself has whitespace built-in. * @param {!Node} dom A tree of XML nodes. * @return {string} Text representation. + * @alias Blockly.Xml.domToText */ const domToText = function(dom) { const text = utilsXml.domToText(dom); @@ -336,6 +345,7 @@ exports.domToText = domToText; * Converts a DOM structure into properly indented text. * @param {!Node} dom A tree of XML elements. * @return {string} Text representation. + * @alias Blockly.Xml.domToPrettyText */ const domToPrettyText = function(dom) { // This function is not guaranteed to be correct for all XML. @@ -370,6 +380,7 @@ exports.domToPrettyText = domToPrettyText; * @return {!Element} A DOM object representing the singular child of the * document element. * @throws if the text doesn't parse. + * @alias Blockly.Xml.textToDom */ const textToDom = function(text) { const doc = utilsXml.textToDomDocument(text); @@ -387,6 +398,7 @@ exports.textToDom = textToDom; * @param {!Element} xml XML DOM. * @param {!Workspace} workspace The workspace. * @return {!Array} An array containing new block IDs. + * @alias Blockly.Xml.clearWorkspaceAndLoadFromXml */ const clearWorkspaceAndLoadFromXml = function(xml, workspace) { workspace.setResizesEnabled(false); @@ -404,6 +416,7 @@ exports.clearWorkspaceAndLoadFromXml = clearWorkspaceAndLoadFromXml; * @return {!Array} An array containing new block IDs. * @suppress {strictModuleDepCheck} Suppress module check while workspace * comments are not bundled in. + * @alias Blockly.Xml.domToWorkspace */ const domToWorkspace = function(xml, workspace) { if (xml instanceof goog.module.get('Blockly.Workspace')) { @@ -511,6 +524,7 @@ exports.domToWorkspace = domToWorkspace; * @param {!Element} xml The XML DOM. * @param {!Workspace} workspace The workspace to add to. * @return {!Array} An array containing new block IDs. + * @alias Blockly.Xml.appendDomToWorkspace */ const appendDomToWorkspace = function(xml, workspace) { let bbox; // Bounding box of the current blocks. @@ -561,6 +575,7 @@ exports.appendDomToWorkspace = appendDomToWorkspace; * @param {!Element} xmlBlock XML block element. * @param {!Workspace} workspace The workspace. * @return {!Block} The root block created. + * @alias Blockly.Xml.domToBlock */ const domToBlock = function(xmlBlock, workspace) { if (xmlBlock instanceof goog.module.get('Blockly.Workspace')) { @@ -632,6 +647,7 @@ exports.domToBlock = domToBlock; * @param {!Element} xmlVariables List of XML variable elements. * @param {!Workspace} workspace The workspace to which the variable * should be added. + * @alias Blockly.Xml.domToVariables */ const domToVariables = function(xmlVariables, workspace) { for (let i = 0; i < xmlVariables.childNodes.length; i++) { @@ -998,6 +1014,7 @@ const domToField = function(block, fieldName, xml) { * Remove any 'next' block (statements in a stack). * @param {!Element|!DocumentFragment} xmlBlock XML block element or an empty * DocumentFragment if the block was an insertion marker. + * @alias Blockly.Xml.deleteNext */ const deleteNext = function(xmlBlock) { for (let i = 0; i < xmlBlock.childNodes.length; i++) { diff --git a/core/zoom_controls.js b/core/zoom_controls.js index 5ba045f50..b5b69c259 100644 --- a/core/zoom_controls.js +++ b/core/zoom_controls.js @@ -10,6 +10,10 @@ */ 'use strict'; +/** + * Object representing a zoom icons. + * @namespace Blockly.ZoomControls + */ goog.module('Blockly.ZoomControls'); const ComponentManager = goog.require('Blockly.ComponentManager'); @@ -38,6 +42,7 @@ goog.require('Blockly.Events.Click'); * @param {!WorkspaceSvg} workspace The workspace to sit in. * @constructor * @implements {IPositionable} + * @alias Blockly.ZoomControls */ const ZoomControls = function(workspace) { /**