diff --git a/src/containers/blocks.jsx b/src/containers/blocks.jsx
index e6d13808734c56ba6f933c2b1118e6812401181a..6ec5771c65e77606da95ce4a7baa06e4d5ca27a0 100644
--- a/src/containers/blocks.jsx
+++ b/src/containers/blocks.jsx
@@ -442,7 +442,7 @@ class Blocks extends React.Component {
             }
         };
 
-        // scratch-blocks implements a menu or custom field as a special kind of block
+        // scratch-blocks implements a menu or custom field as a special kind of block ("shadow" block)
         // these actually define blocks and MUST run regardless of the UI state
         defineBlocks(
             Object.getOwnPropertyNames(categoryInfo.customFieldTypes)
diff --git a/src/lib/define-dynamic-block.js b/src/lib/define-dynamic-block.js
index 4f561d6cdeeac6dc2cb998e04f5d566490e32b93..af1aa42794b8f3646aa098fd117a20158c7d68d6 100644
--- a/src/lib/define-dynamic-block.js
+++ b/src/lib/define-dynamic-block.js
@@ -3,6 +3,16 @@
 import ArgumentType from 'scratch-vm/src/extension-support/argument-type';
 import BlockType from 'scratch-vm/src/extension-support/block-type';
 
+/**
+ * Define a block using extension info which has the ability to dynamically determine (and update) its layout.
+ * This functionality is used for extension blocks which can change its properties based on different state
+ * information. For example, the `control_stop` block changes its shape based on which menu item is selected
+ * and a variable block changes its text to reflect the variable name without using an editable field.
+ * @param {object} ScratchBlocks - The ScratchBlocks name space.
+ * @param {object} categoryInfo - Information about this block's extension category, including any menus and icons.
+ * @param {object} staticBlockInfo - The base block information before any dynamic changes.
+ * @param {string} extendedOpcode - The opcode for the block (including the extension ID).
+ */
 // TODO: grow this until it can fully replace `_convertForScratchBlocks` in the VM runtime
 const defineDynamicBlock = (ScratchBlocks, categoryInfo, staticBlockInfo, extendedOpcode) => ({
     init: function () {