Update comments

Author: janodvarko

lib/data-tooltip.js

@@ -34,10 +34,14 @@ const XHTML_NS = "http://www.w3.org/1999/xhtml";
 const ToolboxOverlayId = FireQueryToolboxOverlay.prototype.overlayId;
 
 /**
- * This object implements a tooltip used in the MarkupView that
- * displays jQuery data as an expandable tree.
- * Content of the tooltip is rendered using an iframe. Content
- * of the iframe is implemented by markup-tooltip.html
+ * This object implements a tooltip used in the MarkupView (Inspector panel)
+ * that displays jQuery data as an expandable tree. Content of the tooltip
+ * is rendered using an iframe. Content of the iframe is implemented
+ * in markup-tooltip.html
+ *
+ * markup-tooltip.html uses require.js and react.js to render its content.
+ * Communication between the iframe content and this object is done
+ * through events (win.dispatchEvent).
  */
 function DataTooltip(options) {
   this.context = options.context;
@@ -57,11 +61,15 @@ DataTooltip.prototype =
   show: makeInfallible(function() {
     this.tooltip.hide(this.target);
 
+    // Initial size of the tooltip. It's changed as the content
+    // requires it (e.g. when the user is expanding tree-nodes
+    // and more space is required).
     let dimensions = {
       width: "300",
       height: "21"
     };
 
+    // Load the content!
     let frameUrl = self.data.url("./markup-tooltip.html");
     this.tooltip.setIFrameContent(dimensions, frameUrl).
       then(this.onTooltipLoaded);
@@ -93,19 +101,26 @@ DataTooltip.prototype =
     Content.exportIntoContentScope(win, contentTrace, "Trace");
     Content.exportIntoContentScope(win, Locale, "Locale");
 
+    // We need the thread object to get client object for grips
+    // (using threadClient.pauseGrip).
     let target = this.toolbox.target;
     target.activeTab.attachThread({}, (response, threadClient) => {
       this.threadClient = threadClient;
 
+      // The tooltip is opened for given jQuery data.
       let data = JSON.stringify(this.jQueryData);
       this.postContentMessage("initialize", data);
 
+      // Do not forget to resume the debugger.
       if (threadClient.paused) {
         threadClient.resume();
       }
     });
   },
 
+  /**
+   * Update size of the tooltip when the content requests that.
+   */
   onTooltipResize: function(size) {
     Trace.sysout("DataTooltip.onTooltipResize;", size);
 
@@ -130,12 +145,19 @@ DataTooltip.prototype =
     });
   },
 
+  /**
+   * Support for UI navigation. If the user clicks on an element
+   * value inside the tooltip, the element is selected within the
+   * Markup View (Inspecto panel).
+   */
   onNavigate: function(grip) {
+    // First, get nodeFront object from give grip. Our FQ actor
+    // implements helper method for that.
     let toolboxOverlay = this.context.getOverlay(ToolboxOverlayId);
     return toolboxOverlay.front.getNode(grip.actor).then(response => {
+      // Show the node in the UI and make sure it's selected.
       var node = response.node;
       this.markup.showNode(node).then(() => {
-        // Mark the node as selected and focused.
         this.markup.markNodeAsSelected(node);
         this.markup.maybeFocusNewSelection();
       });
@@ -144,6 +166,9 @@ DataTooltip.prototype =
 
   // Tooltip Content Communication
 
+  /**
+   * Handle events coming from the tooltip iframe (content).
+   */
   onContentMessage: function(event) {
     //Trace.sysout("DataTooltip.onContentMessage;", event);
 
@@ -165,7 +190,7 @@ DataTooltip.prototype =
   },
 
   /**
-   * Send message to the content scope (panel's iframe)
+   * Send message to the content scope (tooltip's iframe)
    */
   postContentMessage: function(type, args) {
     let win = this.contentWin;
@@ -209,7 +234,7 @@ if (!Tooltip.prototype.setIFrameContent) {
     }
     iframe.addEventListener("load", onLoad, true);
 
-    // load the document from url into the iframe
+    // Load the document from url into the iframe
     iframe.setAttribute("src", url);
 
     // Put the iframe in the tooltip

lib/firequery-actor.js

@@ -66,6 +66,13 @@ function expectState(expectedState, method) {
  * always done through RDP (Remote Debugging Protocol). Read more about
  * {@link https://wiki.mozilla.org/Remote_Debugging_Protocol|RDP}.
  *
+ * In order to run the actor on Firefox OS device, you need to make sure
+ * that 'devtools.debugger.forbid-certified-apps' is set to false on that
+ * device.
+ *
+ * Read more about restricted privileges on Firefox OS:
+ * https://bugzilla.mozilla.org/show_bug.cgi?id=977443#c11
+ *
  * Read more about Protocol API:
  * https://github.com/mozilla/gecko-dev/blob/master/toolkit/devtools/server/docs/protocol.js.md
  */
@@ -143,7 +150,7 @@ var FireQueryActor = ActorClass(
 
     this.state = "attached";
 
-    // xxxHonza: it's sometimes undefined (e.g. when enabling installed FQ).
+    // xxxHonza: it's sometimes undefined (e.g. when enabling installed FQ) FIXME
     let Previewers = DebuggerServer.ObjectActorPreviewers;
     if (typeof Previewers != "undefined") {
       Previewers.Object.unshift(this.onBuildPreview);
@@ -250,7 +257,7 @@ var FireQueryActor = ActorClass(
           data = makeDebuggeeValueIfNeeded(actor.obj, data);
           grip.preview.jQueryData = this.createValueGrip(actor, data);
 
-          // xxxHonza: generate preview for the data?
+          // xxxHonza: generate preview for the jQuery.data?
         }
       } else {
         preview.items.push(null);
@@ -267,7 +274,7 @@ var FireQueryActor = ActorClass(
   }),
 
   createValueGrip: function(actor, value) {
-    // Introduced in Fx42
+    // actor.hooks field has been introduced in Fx42
     if (actor.hooks) {
       return actor.hooks.createValueGrip(value);
     }
@@ -305,6 +312,11 @@ var FireQueryActor = ActorClass(
     }
   }),
 
+  /**
+   * Patch jQuery (in order to get modification events) as soon as
+   * jQuery has been loaded on the page. Either by the page itself
+   * or by the 'jQuerify' button in the Console panel toolbar.
+   */
   onJQueryDetected: makeInfallible(function(event) {
     let win = this.parent.window.wrappedJSObject;
 
@@ -314,6 +326,12 @@ var FireQueryActor = ActorClass(
     win.eval(this.patch);
   }),
 
+  /**
+   * Sent from the page (by the jQuery patch) when jQuery.data
+   * has been modified. The method forwards that event through
+   * "data-modified" packet to the client side, so the Inspector
+   * panel can be dynamically updated.
+   */
   onDataModified: makeInfallible(function(event) {
     let win = this.parent.window.wrappedJSObject;
 

lib/firequery-toolbox-overlay.js

@@ -43,6 +43,12 @@ const JQUERYPATCH = "chrome://firequery-resources/content/jquery2-patch.js";
  *
  * FireQuery uses the overlay to register and attach/detach the
  * backend actor.
+ *
+ * The rest of the extension can access actor's front object
+ * as follows:
+ *
+ * let toolboxOverlay = this.context.getOverlay(ToolboxOverlayId);
+ * let front = toolboxOverlay.front;
  */
 const FireQueryToolboxOverlay = Class(
 /** @lends FireQueryToolboxOverlay */
@@ -121,7 +127,7 @@ const FireQueryToolboxOverlay = Class(
   detach: makeInfallible(function() {
     Trace.sysout("FireQueryToolboxOverlay.detach;");
 
-    // xxxHonza: TODO
+    // xxxHonza: TODO clean up?
 
     // Emit an event indicating that the detach process is done. This
     // can be used e.g. by tests.