chore: add top-level inline docs to bubbles icons and inputs (#7190)

* chore: add top-level inline docs to bubbles icons and inputs

* chore: fixup for PR comments

core/bubbles/bubble.ts

@@ -16,6 +16,11 @@ import {Size} from '../utils/size.js';
 import {Svg} from '../utils/svg.js';
 import {WorkspaceSvg} from '../workspace_svg.js';
 
+/**
+ * The abstract pop-up bubble class. This creates a UI that looks like a speech
+ * bubble, where it has a "tail" that points to the block, and a "head" that
+ * displays arbitrary svg elements.
+ */
 export abstract class Bubble implements IBubble {
   /** The width of the border around the bubble. */
   static readonly BORDER_WIDTH = 6;

core/bubbles/mini_workspace_bubble.ts

@@ -15,6 +15,10 @@ import type {Rect} from '../utils/rect.js';
 import {Size} from '../utils/size.js';
 import type {WorkspaceSvg} from '../workspace_svg.js';
 
+/**
+ * A bubble that contains a mini-workspace which can hold arbitrary blocks.
+ * Used by the mutator icon.
+ */
 export class MiniWorkspaceBubble extends Bubble {
   /**
    * The minimum amount of change to the mini workspace view to trigger

core/bubbles/text_bubble.ts

@@ -12,6 +12,9 @@ import {Size} from '../utils/size.js';
 import {Svg} from '../utils/svg.js';
 import {WorkspaceSvg} from '../workspace_svg.js';
 
+/**
+ * A bubble that displays non-editable text. Used by the warning icon.
+ */
 export class TextBubble extends Bubble {
   private paragraph: SVGTextElement;
 

core/bubbles/textinput_bubble.ts

@@ -15,6 +15,10 @@ import * as touch from '../touch.js';
 import {WorkspaceSvg} from '../workspace_svg.js';
 import {browserEvents} from '../utils.js';
 
+/**
+ * A bubble that displays editable text. It can also be resized by the user.
+ * Used by the comment icon.
+ */
 export class TextInputBubble extends Bubble {
   /** The root of the elements specific to the text element. */
   private inputRoot: SVGForeignObjectElement;

core/icons/comment_icon.ts

@@ -33,6 +33,9 @@ const DEFAULT_BUBBLE_WIDTH = 160;
 /** The default height in workspace-scale units of the text input bubble. */
 const DEFAULT_BUBBLE_HEIGHT = 80;
 
+/**
+ * An icon which allows the user to add comment text to a block.
+ */
 export class CommentIcon extends Icon implements IHasBubble, ISerializable {
   /** The type string used to identify this icon. */
   static readonly TYPE = IconType.COMMENT;

core/icons/exceptions.ts

@@ -6,6 +6,9 @@
 
 import type {IIcon} from '../interfaces/i_icon.js';
 
+/**
+ * Thrown when you add more than one icon of the same type to a block.
+ */
 export class DuplicateIconType extends Error {
   /**
    * @internal

core/icons/icon.ts

@@ -15,6 +15,12 @@ import {Size} from '../utils/size.js';
 import {Svg} from '../utils/svg.js';
 import type {IconType} from './icon_types.js';
 
+/**
+ * The abstract icon class. Icons are visual elements that live in the top-start
+ * corner of the block. Usually they provide more "meta" information about a
+ * block (such as warnings or comments) as opposed to fields, which provide
+ * "actual" information, related to how a block functions.
+ */
 export abstract class Icon implements IIcon {
   /**
    * The position of this icon relative to its blocks top-start,

core/icons/icon_types.ts

@@ -9,6 +9,9 @@ import {CommentIcon} from './comment_icon.js';
 import {MutatorIcon} from './mutator_icon.js';
 import {WarningIcon} from './warning_icon.js';
 
+/**
+ * Defines the type of an icon, so that it can be retrieved from block.getIcon
+ */
 export class IconType<_T extends IIcon> {
   /** @param name The name of the registry type. */
   constructor(private readonly name: string) {}

core/icons/mutator_icon.ts

@@ -35,6 +35,12 @@ const SIZE = 17;
  */
 const WORKSPACE_MARGIN = 16;
 
+/**
+ * An icon that allows the user to change the shape of the block.
+ *
+ * For example, it could be used to add additional fields or inputs to
+ * the block.
+ */
 export class MutatorIcon extends Icon implements IHasBubble {
   /** The type string used to identify this icon. */
   static readonly TYPE = IconType.MUTATOR;

core/icons/warning_icon.ts

@@ -22,6 +22,12 @@ import {IconType} from './icon_types.js';
 /** The size of the warning icon in workspace-scale units. */
 const SIZE = 17;
 
+/**
+ * An icon that warns the user that something is wrong with their block.
+ *
+ * For example, this could be used to warn them about incorrect field values,
+ * or incorrect placement of the block (putting it somewhere it doesn't belong).
+ */
 export class WarningIcon extends Icon implements IHasBubble {
   /** The type string used to identify this icon. */
   static readonly TYPE = IconType.WARNING;

core/inputs/input.ts

@@ -24,9 +24,7 @@ import * as fieldRegistry from '../field_registry.js';
 import type {RenderedConnection} from '../rendered_connection.js';
 import {inputTypes} from './input_types.js';
 
-/**
- * Class for an input with an optional field.
- */
+/** Class for an input with optional fields. */
 export class Input {
   fieldRow: Field[] = [];
   /** Alignment of input's fields (left, right or centre). */