diff --git a/core/block.ts b/core/block.ts
index d57043e55..8f64b20a2 100644
--- a/core/block.ts
+++ b/core/block.ts
@@ -865,6 +865,8 @@ export class Block implements IASTNodeLocation, IDeletable {
 
   /**
    * Set whether this block is a shadow block or not.
+   * This method is internal and should not be called by users of Blockly. To
+   * create shadow blocks programmatically call connection.setShadowState
    *
    * @param shadow True if a shadow.
    * @internal
diff --git a/core/block_svg.ts b/core/block_svg.ts
index 5ead73340..2ec157fa8 100644
--- a/core/block_svg.ts
+++ b/core/block_svg.ts
@@ -755,6 +755,8 @@ export class BlockSvg
 
   /**
    * Sets whether this block is a shadow block or not.
+   * This method is internal and should not be called by users of Blockly. To
+   * create shadow blocks programmatically call connection.setShadowState
    *
    * @param shadow True if a shadow.
    * @internal