add comments suggested in code review

src/lib/define-dynamic-block.js

@@ -31,8 +31,11 @@ const defineDynamicBlock = (ScratchBlocks, categoryInfo, staticBlockInfo, extend
         if (staticBlockInfo.blockIconURI || categoryInfo.blockIconURI) {
             blockJson.extensions = ['scratch_extension'];
         }
+        // initialize the basics of the block, to be overridden & extended later by `domToMutation`
         this.jsonInit(blockJson);
+        // initialize the cached block info used to carry block info from `domToMutation` to `mutationToDom`
         this.blockInfoText = '{}';
+        // we need a block info update (through `domToMutation`) before we have a completely initialized block
         this.needsBlockInfoUpdate = true;
     },
     mutationToDom: function () {

src/lib/make-toolbox-xml.js

@@ -716,7 +716,8 @@ const xmlClose = '</xml>';
 /**
  * @param {!boolean} isStage - Whether the toolbox is for a stage-type target.
  * @param {?string} targetId - The current editing target
- * @param {?Array.<object>} categoriesXML - optional array of `{id,xml}` for categories.
+ * @param {?Array.<object>} categoriesXML - optional array of `{id,xml}` for categories. This can include both core
+ * and other extensions: core extensions will be placed in the normal Scratch order; others will go at the bottom.
  * @property {string} id - the extension / category ID.
  * @property {string} xml - the `<category>...</category>` XML for this extension / category.
  * @param {?string} costumeName - The name of the default selected costume dropdown.