Add additional inline comments and fix error message

Author: parlough

pkgs/inject_dartpad/example/inject_dartpad_example.dart

@@ -2,21 +2,27 @@ import 'package:inject_dartpad/inject_dartpad.dart';
 import 'package:web/web.dart' as web;
 
 void main() async {
+  // Create the embedded DartPad instance manager.
   final dartPad = EmbeddedDartPad.create(
     iframeId: 'my-dartpad',
     theme: DartPadTheme.light,
   );
 
+  // Initialize the embedded DartPad.
   await dartPad.initialize(
     addToDocument: (iframe) {
+      // Add any extra styles or attributes to the created iframe.
       iframe.style.height = '560';
 
+      // Add the iframe to the document body.
+      // This is necessary for the embed to load.
       web.document.body!.append(iframe);
     },
   );
 
-  dartPad.updateCode('''
+  // After awaiting initialization, you can update the code in the DartPad.
+  dartPad.updateCode(r'''
 void main() {
-  print("Hello, I'm Dash!");
+  print('Hello, I am Dash!');
 }''');
 }

pkgs/inject_dartpad/lib/inject_dartpad.dart

@@ -114,15 +114,20 @@ final class EmbeddedDartPad {
   }) async {
     if (_initialized) return;
 
+    // Start listening for the 'ready' message from the embedded DartPad.
     late final JSExportedDartFunction readyHandler;
     readyHandler = (web.MessageEvent event) {
       if (event.data case _EmbedReadyMessage(type: 'ready', :final sender?)) {
+        // Verify the message is sent from the corresponding iframe,
+        // in case there are multiple DartPads being embedded at the same time.
         if (sender != iframeId) {
           return;
         }
 
         web.window.removeEventListener('message', readyHandler);
         if (!_initialized) {
+          // Signal to the caller that the DartPad is ready
+          // for Dart code to be injected.
           _initializedCompleter.complete();
         }
       }
@@ -136,6 +141,9 @@ final class EmbeddedDartPad {
       ..name = iframeId
       ..loading = 'lazy'
       ..allow = 'clipboard-write';
+
+    // Give the caller a chance to modify other attributes of the iframe and
+    // attach it to their desired location in the document.
     addToDocument(iframe);
 
     await _initializedCompleter.future;

pkgs/inject_dartpad/lib/inject_dartpad.js

@@ -1585,6 +1585,7 @@ try{r=s
 r.a=A.H(r.a,a,", ")}finally{$.p.pop()}s.a+=c
 r=s.a
 return r.charCodeAt(0)==0?r:r},
+mp(a){A.qw(a)},
 Hh(a,b,c){var s,r,q,p,o,n,m="IPv4 address should contain exactly 4 parts",l="each part must be in the range 0..255",k=new A.cS(a),j=new Uint8Array(4)
 for(s=b,r=s,q=0;s<c;++s){p=a.charCodeAt(s)
 if(p!==46){if((p^48)>9)k.$2("invalid character",s)}else{if(q===3)k.$2(m,s)
@@ -1866,7 +1867,8 @@ var $async$E=A.l(function(a,b){if(a===1)return A.x(b,r)
 while(true)switch(s){case 0:o=v.G.document.querySelectorAll("pre > code[data-dartpad]:only-child")
 n=A.J([],t.F)
 for(q=0;q<o.length;++q){p=o.item(q)
-n.push(A.f(p==null?A.A(p):p,q))}s=2
+if(p==null)p=A.A(p)
+n.push(A.f(p,"embedded-dartpad-"+q))}s=2
 return A.j(A.v(n,t.U),$async$E)
 case 2:return A.y(null,r)}})
 return A.D($async$E,r)},
@@ -1912,7 +1914,7 @@ a1=new A.Dn(h,g,m&&B.xB.nC(a0,"//")?"":f,c,a0,e,d).gnD()
 k=new A.vs($.X3,t.D)
 a2=new A.NG(o,a1,new A.Zf(k,t.h))
 s=3
-return A.j(a2.qw(new A.i6(a5,a4)),$async$f)
+return A.j(a2.qw(new A.i6(a5,a4,p)),$async$f)
 case 3:if((k.a&30)===0)A.vh(A.PV("EmbeddedDartPad.initialize must be called and awaited before updating the embedded source code."))
 a3=v.G.document.getElementById(o)
 if(a3==null)A.vh(A.PV("Failed to find iframe with an id of "+o+" in the document. Have you added the iframe to the document?"))
@@ -1924,8 +1926,9 @@ s=1
 break
 case 1:return A.y(q,r)}})
 return A.D($async$f,r)},
-i6:function i6(a,b){this.a=a
-this.b=b},
+i6:function i6(a,b,c){this.a=a
+this.b=b
+this.c=c},
 qw(a){if(typeof dartPrint=="function"){dartPrint(a)
 return}if(typeof console=="object"&&typeof console.log!="undefined"){console.log(a)
 return}if(typeof print=="function"){print(a)
@@ -2853,7 +2856,8 @@ k.appendChild(a)
 s=this.b
 s.replaceWith(k)
 if(a.contentWindow==null){k.replaceWith(s)
-A.qw("Failed to inject embedded DartPad with content:\n")}},
+A.mp("Failed to inject embedded DartPad with content:\n")
+A.mp(this.c)}},
 $S:20};(function aliases(){var s=J.zh.prototype
 s.u=s["["]})();(function installTearOffs(){var s=hunkHelpers._static_1,r=hunkHelpers._static_0
 s(A,"EX","ZV",1)

pkgs/inject_dartpad/web/inject_dartpad.dart

@@ -15,13 +15,21 @@ void main() async {
 
   await [
     for (var index = 0; index < codeElements.length; index += 1)
-      _injectEmbed(codeElements.item(index) as web.HTMLElement, index),
+      _injectEmbed(
+        codeElements.item(index) as web.HTMLElement,
+        'embedded-dartpad-$index',
+      ),
   ].wait;
 }
 
+/// Extract the code from the element,
+/// replace it with an embedded DartPad iframe,
+/// and inject the extracted code.
+///
+/// Each embed on a single should have a unique [iframeId].
 Future<EmbeddedDartPad?> _injectEmbed(
   web.HTMLElement codeElement,
-  int embedNumber,
+  String iframeId,
 ) async {
   final parent = codeElement.parentElement;
   if (parent == null) return null;
@@ -32,7 +40,7 @@ Future<EmbeddedDartPad?> _injectEmbed(
   if (content.isEmpty) return null;
 
   final embeddedDartPad = EmbeddedDartPad.create(
-    iframeId: 'embedded-dartpad-$embedNumber',
+    iframeId: 'embedded-dartpad-$iframeId',
     host: switch (codeElement.getAttribute('data-url')) {
       final specifiedHost? when specifiedHost.isNotEmpty => specifiedHost,
       _ => null,
@@ -46,6 +54,9 @@ Future<EmbeddedDartPad?> _injectEmbed(
   await embeddedDartPad.initialize(
     addToDocument: (iframe) {
       iframe.classList.add('embedded-dartpad');
+
+      // Extract the configuration options specified on
+      // the sites embedding DartPad (dart.dev and docs.flutter.dev).
       if (codeElement.getAttribute('title') case final title?
           when title.isNotEmpty) {
         iframe.setAttribute('title', title);
@@ -63,16 +74,22 @@ Future<EmbeddedDartPad?> _injectEmbed(
 
       final host = web.HTMLDivElement();
       host.appendChild(iframe);
+      // Add the iframe to the DOM so it has a chance to load.
       parent.replaceWith(host);
 
       final contentWindow = iframe.contentWindow;
       if (contentWindow == null) {
+        // If the iframe wasn't initialized correctly,
+        // fall back to the original code block.
         host.replaceWith(parent);
+
         print('Failed to inject embedded DartPad with content:\n');
+        print(content);
       }
     },
   );
 
+  // Now that the embedded DartPad is initialized, inject the extracted code.
   embeddedDartPad.updateCode(content);
 
   return embeddedDartPad;