docs(blocks): block.ts and blocks/* JSDoc / formatting / etc. cleanup (#8431)

* docs(block): Improve documentation for well-known block methods

  Improve the JSDocs for the declarations of well-known block
  methods:

  - getDeveloperVariables
  - compose
  - decompose
  - saveConnections

* docs(blocks): Improve block comments

  Fix JSDoc formatting in both core/block.ts and blocks/*, as well as
  making various other minor improvments.

* chore(blocks): Remove one unexported const

blocks/procedures.ts

@@ -1206,7 +1206,7 @@ blocks['procedures_callreturn'] = {
     this.appendDummyInput('TOPROW').appendField('', 'NAME');
     this.setOutput(true);
     this.setStyle('procedure_blocks');
-    // Tooltip is set in domToMutation.
+    // Tooltip is set in renameProcedure.
     this.setHelpUrl(Msg['PROCEDURES_CALLRETURN_HELPURL']);
     this.arguments_ = [];
     this.argumentVarModels_ = [];

blocks/text.ts

@@ -438,6 +438,11 @@ const PROMPT_COMMON = {
   domToMutation: function (this: PromptCommonBlock, xmlElement: Element) {
     this.updateType_(xmlElement.getAttribute('type')!);
   },
+
+  // These blocks do not need JSO serialization hooks (saveExtraState
+  // and loadExtraState) because the state of this object is already
+  // encoded in the dropdown values.
+  // XML hooks are kept for backwards compatibility.
 };
 
 blocks['text_prompt_ext'] = {
@@ -468,16 +473,11 @@ blocks['text_prompt_ext'] = {
         : Msg['TEXT_PROMPT_TOOLTIP_NUMBER'];
     });
   },
-
-  // This block does not need JSO serialization hooks (saveExtraState and
-  // loadExtraState) because the state of this object is already encoded in the
-  // dropdown values.
-  // XML hooks are kept for backwards compatibility.
 };
 
 type PromptBlock = Block & PromptCommonMixin & QuoteImageMixin;
 
-const TEXT_PROMPT_BLOCK = {
+blocks['text_prompt'] = {
   ...PROMPT_COMMON,
   /**
    * Block for prompt function (internal message).
@@ -520,8 +520,6 @@ const TEXT_PROMPT_BLOCK = {
   },
 };
 
-blocks['text_prompt'] = TEXT_PROMPT_BLOCK;
-
 blocks['text_count'] = {
   /**
    * Block for counting how many times one string appears within another string.
@@ -666,7 +664,7 @@ const QUOTE_IMAGE_MIXIN = {
    * closing double quote. The selected quote will be adapted for RTL blocks.
    *
    * @param open If the image should be open quote (“ in LTR).
-   *                       Otherwise, a closing quote is used (” in LTR).
+   *     Otherwise, a closing quote is used (” in LTR).
    * @returns The new field.
    */
   newQuote_: function (this: QuoteImageBlock, open: boolean): FieldImage {

core/block.ts

@@ -143,24 +143,31 @@ export class Block implements IASTNodeLocation {
   suppressPrefixSuffix: boolean | null = false;
 
   /**
-   * An optional property for declaring developer variables.  Return a list of
+   * An optional method for declaring developer variables, to be used
-   * variable names for use by generators.  Developer variables are never
+   * by generators.  Developer variables are never shown to the user,
-   * shown to the user, but are declared as global variables in the generated
+   * but are declared as global variables in the generated code.
-   * code.
+   *
+   * @returns a list of developer variable names.
    */
   getDeveloperVariables?: () => string[];
 
   /**
-   * An optional function that reconfigures the block based on the contents of
+   * An optional method that reconfigures the block based on the
-   * the mutator dialog.
+   * contents of the mutator dialog.
+   *
+   * @param rootBlock The root block in the mutator flyout.
    */
-  compose?: (p1: Block) => void;
+  compose?: (rootBlock: Block) => void;
 
   /**
-   * An optional function that populates the mutator's dialog with
+   * An optional function that populates the mutator flyout with
-   * this block's components.
+   * blocks representing this block's configuration.
+   *
+   * @param workspace The mutator flyout's workspace.
+   * @returns The root block created in the flyout's workspace.
    */
-  decompose?: (p1: Workspace) => Block;
+  decompose?: (workspace: Workspace) => Block;
+
   id: string;
   outputConnection: Connection | null = null;
   nextConnection: Connection | null = null;
@@ -716,7 +723,7 @@ export class Block implements IASTNodeLocation {
     }
 
     // Check that block is connected to new parent if new parent is not null and
-    //    that block is not connected to superior one if new parent is null.
+    // that block is not connected to superior one if new parent is null.
     const targetBlock =
       (this.previousConnection && this.previousConnection.targetBlock()) ||
       (this.outputConnection && this.outputConnection.targetBlock());
@@ -734,14 +741,13 @@ export class Block implements IASTNodeLocation {
     }
 
     // This block hasn't actually moved on-screen, so there's no need to
-    // update
+    // update its connection locations.
-    //     its connection locations.
     if (this.parentBlock_) {
       // Remove this block from the old parent's child list.
       arrayUtils.removeElem(this.parentBlock_.childBlocks_, this);
     } else {
-      // New parent must be non-null so remove this block from the workspace's
+      // New parent must be non-null so remove this block from the
-      //     list of top-most blocks.
+      // workspace's list of top-most blocks.
       this.workspace.removeTopBlock(this);
     }
 

core/block_svg.ts

@@ -92,7 +92,25 @@ export class BlockSvg
   static readonly COLLAPSED_WARNING_ID = 'TEMP_COLLAPSED_WARNING_';
   override decompose?: (p1: Workspace) => BlockSvg;
   // override compose?: ((p1: BlockSvg) => void)|null;
-  saveConnections?: (p1: BlockSvg) => void;
+
+  /**
+   * An optional method which saves a record of blocks connected to
+   * this block so they can be later restored after this block is
+   * recoomposed (reconfigured).  Typically records the connected
+   * blocks on properties on blocks in the mutator flyout, so that
+   * rearranging those component blocks will automatically rearrange
+   * the corresponding connected blocks on this block after this block
+   * is recomposed.
+   *
+   * To keep the saved connection information up-to-date, MutatorIcon
+   * arranges for an event listener to call this method any time the
+   * mutator flyout is open and a change occurs on this block's
+   * workspace.
+   *
+   * @param rootBlock The root block in the mutator flyout.
+   */
+  saveConnections?: (rootBlock: BlockSvg) => void;
+
   customContextMenu?: (
     p1: Array<ContextMenuOption | LegacyContextMenuOption>,
   ) => void;