Add comments about moving the Vomnibar to an iframe

background_scripts/main.coffee

@@ -635,8 +635,8 @@ getCurrFrameIndex = (frames) ->
     return i if frames[i].id == focusedFrame
   frames.length + 1
 
-# Send message back to the tab unchanged.
-# Frames in the same tab can use this to communicate securely.
+# Send message back to the tab unchanged. This allows different frames from the same tab to message eachother
+# while avoiding security concerns such as eavesdropping or message spoofing.
 echo = (request, sender) ->
   delete request.handler # No need to send this information
   chrome.tabs.sendMessage(sender.tab.id, request)

content_scripts/vomnibar.coffee

@@ -1,3 +1,6 @@
+#
+# This wraps the vomnibar iframe, which we inject into the page to provide the vomnibar.
+#
 Vomnibar =
   vomnibarElement: null
 
@@ -21,6 +24,11 @@ Vomnibar =
     newTab: true
   }
 
+  # This function opens the vomnibar. It accepts options, a map with the values:
+  #   completer   - The completer to fetch results from.
+  #   query       - Optional. Text to prefill the Vomnibar with.
+  #   selectFirst - Optional, boolean. Whether to select the first entry.
+  #   newTab      - Optional, boolean. Whether to open the result in a new tab.
   open: (options) ->
     unless @vomnibarElement?
       @vomnibarElement = document.createElement "iframe"

pages/vomnibar.coffee

@@ -1,3 +1,8 @@
+#
+# This controls the contents of the Vomnibar iframe. We use an iframe to avoid changing the selection on the
+# page (useful for bookmarklets), ensure that the Vomnibar style is unaffected by the page, and simplify key
+# handling in vimium_frontend.coffee
+#
 Vomnibar =
   vomnibarUI: null # the dialog instance for this window
   completers: {}