Noissue - Improve comments for composer code

composer.postload.js

 /*
  * This file is part of Adblock Plus <https://adblockplus.org/>,
  * Copyright (C) 2006-2016 Eyeo GmbH
  *
  * Adblock Plus is free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License version 3 as
  * published by the Free Software Foundation.
  *
  * Adblock Plus is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
@@ skipping 100 matching lines @@
     }
   }
 
   // We reached the document root without finding a blockable element.
   callback(null);
 }
 
 
 /* Element highlighting */
 
-// Adds an overlay to an element, which is probably a Flash object.
+// Adds an overlay to an element in order to highlight it.
 function addElementOverlay(element)
 {
   let position = "absolute";
   let offsetX = window.scrollX;
   let offsetY = window.scrollY;
 
   for (let e = element; e; e = e.parentElement)
   {
     let style = getComputedStyle(e);
 
@@ skipping 75 matching lines @@
 
       element.style.removeProperty("background-color");
       element.style.setProperty(
         "background-color",
         originalBackgroundColor,
         originalBackgroundColorPriority
       );
     };
   };
 
+  // If this element is an overlay that we've created previously then we need
+  // to give it a background colour. Otherwise we need to create an overlay
+  // and then recurse in order to set the overlay's background colour.
   if ("prisoner" in element)
     highlightWithStyleAttribute();
   else
     highlightWithOverlay();
 }
 
 function unhighlightElement(element)
 {
   if (element && "_unhighlight" in element)
   {
@@ skipping 110 matching lines @@
 
 
 /* Element selection */
 
 // Start highlighting elements yellow as the mouse moves over them, when one is
 // chosen launch the popup dialog for the user to confirm the generated filters.
 function startPickingElement()
 {
   currentlyPickingElement = true;
 
-  // Add overlays for blockable elements that don't emit mouse events,
-  // so that they can still be selected.
+  // Add (currently invisible) overlays for blockable elements that don't emit
+  // mouse events, so that they can still be selected.
   Array.prototype.forEach.call(
     document.querySelectorAll("object,embed,iframe,frame"),
     element =>
     {
       getFiltersForElement(element, filters =>
       {
         if (filters.length > 0)
           addElementOverlay(element);
       });
     }
@@ skipping 218 matching lines @@
             }
           });
         }
         break;
     }
   });
 
   if (window == window.top)
     ext.backgroundPage.sendMessage({type: "composer.ready"});
 }