[Chrome extension] Added JSDocs to pdfHandler.js

And a small refactor to reduce the LOC in the onHeadersReceived
callback, to improve the readability of the code.

extensions/chrome/pdfHandler.js

@@ -19,10 +19,21 @@ limitations under the License.
 
 'use strict';
 
+/**
+ * @param {Object} details First argument of the webRequest.onHeadersReceived
+ *                         event. The property "url" is read.
+ * @return {boolean} True if the PDF download was initiated by PDF.js
+ */
 function isPdfDownloadable(details) {
   return details.url.indexOf('pdfjs.action=download') >= 0;
 }
 
+/**
+ * Insert the content script in a tab which renders the PDF viewer.
+ * @param {number} tabId ID of the tab used by the Chrome APIs.
+ * @param {string} url URL of the PDF file. Used to detect whether the viewer
+ *                     should be activated in a specific (i)frame.
+ */
 function insertPDFJSForTab(tabId, url) {
   chrome.tabs.executeScript(tabId, {
     file: 'insertviewer.js',
@@ -35,6 +46,13 @@ function insertPDFJSForTab(tabId, url) {
     });
   });
 }
+
+/**
+ * Try to render the PDF viewer when (a frame within) a tab unloads.
+ * This indicates that a PDF file may be loading.
+ * @param {number} tabId ID of the tab used by the Chrome APIs.
+ * @param {string} url The URL of the pdf file.
+ */
 function activatePDFJSForTab(tabId, url) {
   chrome.tabs.onUpdated.addListener(function listener(_tabId) {
     if (tabId === _tabId) {
@@ -44,60 +62,78 @@ function activatePDFJSForTab(tabId, url) {
   });
 }
 
-chrome.webRequest.onHeadersReceived.addListener(
+/**
-  function(details) {
+ * Get the header from the list of headers for a given name.
-    // Check if the response is a PDF file
+ * @param {Array} headers responseHeaders of webRequest.onHeadersReceived
-    var isPDF = false;
+ * @return {undefined|{name: string, value: string}} The header, if found.
-    var headers = details.responseHeaders;
+ */
-    var header, i;
+function getHeaderFromHeaders(headers, headerName) {
-    var cdHeader;
+  for (var i=0; i<headers.length; ++i) {
-    if (!headers)
+    var header = headers[i];
-      return;
+    if (header.name.toLowerCase() === headerName) {
-    for (i=0; i<headers.length; ++i) {
+      return header;
-      header = headers[i];
+    }
-      if (header.name.toLowerCase() == 'content-type') {
+  }
+}
+
+/**
+ * Check if the request is a PDF file.
+ * @param {Object} details First argument of the webRequest.onHeadersReceived
+ *                         event. The properties "responseHeaders" and "url"
+ *                         are read.
+ * @return {boolean} True if the resource is a PDF file.
+ */
+function isPdfFile(details) {
+  var header = getHeaderFromHeaders(details.responseHeaders, 'content-type');
+  if (header) {
     var headerValue = header.value.toLowerCase().split(';',1)[0].trim();
-        isPDF = headerValue === 'application/pdf' ||
+    return headerValue === 'application/pdf' ||
       headerValue === 'application/octet-stream' &&
       details.url.toLowerCase().indexOf('.pdf') > 0;
-        break;
   }
 }
-    if (!isPDF)
-      return;
 
-    if (isPdfDownloadable(details)) {
+/**
-      // Force download by ensuring that Content-Disposition: attachment is set
+ * Takes a set of headers, and set "Content-Disposition: attachment".
-      if (!cdHeader) {
+ * @param {Object} details First argument of the webRequest.onHeadersReceived
-        for (; i<headers.length; ++i) {
+ *                         event. The property "responseHeaders" is read and
-          header = headers[i];
+ *                         modified if needed.
-          if (header.name.toLowerCase() == 'content-disposition') {
+ * @return {Object|undefined} The return value for the onHeadersReceived event.
-            cdHeader = header;
+ *                            Object with key "responseHeaders" if the headers
-            break;
+ *                            have been modified, undefined otherwise.
-          }
+ */
-        }
+function getHeadersWithContentDispositionAttachment(details) {
-      }
+    var headers = details.responseHeaders;
+    var cdHeader = getHeaderFromHeaders(headers, 'content-disposition');
     if (!cdHeader) {
-        cdHeader = {name: 'Content-Disposition', value: ''};
+      cdHeader = {name: 'Content-Disposition'};
       headers.push(cdHeader);
     }
-      if (cdHeader.value.toLowerCase().indexOf('attachment') === -1) {
+    if (!/^attachment/i.test(cdHeader.value)) {
       cdHeader.value = 'attachment' + cdHeader.value.replace(/^[^;]+/i, '');
-        return {
+      return { responseHeaders: headers };
-          responseHeaders: headers
+    }
-        };
 }
+
+chrome.webRequest.onHeadersReceived.addListener(
+  function(details) {
+    if (!isPdfFile(details))
       return;
+
+    if (isPdfDownloadable(details)) {
+      // Force download by ensuring that Content-Disposition: attachment is set
+      return getHeadersWithContentDispositionAttachment(details);
     }
 
-    // Replace frame's content with the PDF viewer
+    // Replace frame's content with the PDF viewer.
-    // This approach maintains the friendly URL in the 
+    // This approach maintains the friendly URL in the location bar.
-    // location bar
     activatePDFJSForTab(details.tabId, details.url);
 
     return {
       responseHeaders: [
         // Set Cache-Control header to avoid downloading a file twice
+        // NOTE: This does not behave as desired, Chrome's network stack is
+        // oblivious for Cache control header modifications.
         {name:'Cache-Control',value:'max-age=600'},
         // Temporary render response as XHTML.
         // Since PDFs are never valid XHTML, the garbage is not going to be