Fix docstrings and error messages

h/browser/chrome/lib/blocklist.js

@@ -1,5 +1,33 @@
 /**
- * A wrapper for the app's /blocklist HTTP endpoint.
+ * A wrapper for the server's uriinfo endpoint.
+ *
+ * Exports a function that makes an HTTP request to the server's uriinfo
+ * endpoint and returns a Promise that resolves to the response. Usage:
+ *
+ *     var blocklist = require('blocklist');
+ *     blocklist(uri).then(function(uriinfo) {
+ *       ...
+ *     });
+ *
+ * This function can be called with the same uri multiple times consecutively
+ * and it'll just keep returning the same Promise - won't make multiple HTTP
+ * requests.
+ *
+ * But if you call the function with a different uri, then call it with the
+ * first uri again, then it _will_ make another request for the first uri.
+ *
+ * Returns a rejected Promise if the HTTP request times out, fails or is
+ * invalid for any reason.
+ *
+ * Returns a rejected Promise is the given uri is undefined.
+ *
+ * @param {String} uri The URI to be checked
+ *
+ * @returns {Promise} A Promise that resolves to an object with two properties:
+ *   1. total:   the number of annotations there are of this URI (Number)
+ *   2. blocked: whether or not this URI is blocklisted (Boolean)
+ *
+ *
  * @module
  */
 'use strict';
@@ -8,12 +36,9 @@ var settings = require('./settings');
 var blocklistPromise;
 
 /**
-  * Make an HTTP request to the /blocklist endpoint and return a Promise that
+  * Make an HTTP request to the uriinfo endpoint and return a Promise that
   * resolves to the value of the response.
   *
-  * This is a helper function for getBlocklistIfUriHasChanged() below, see
-  * that function's docstring for more details.
-  *
   */
 function getBlocklist(uri) {
   if (uri === undefined) {
@@ -35,23 +60,23 @@ function getBlocklist(uri) {
         total = blocklist.total;
         blocked = blocklist.blocked;
       } catch (e) {
-        errorMsg = 'Received invalid JSON from the /blocklist endpoint: ';
+        errorMsg = 'Received invalid JSON from the server: ';
         errorMsg = errorMsg + this.responseText;
         console.error(errorMsg);
         reject({reason: errorMsg});
         return;
       }
 
       if (typeof total !== 'number') {
-        errorMsg = 'Received invalid total from the /blocklist endpoint: ';
+        errorMsg = 'Received invalid total from the server: ';
         errorMsg = errorMsg + total;
         console.error(errorMsg);
         reject({reason: errorMsg});
         return;
       }
 
       if (typeof blocked !== 'boolean') {
-        errorMsg = 'Received invalid blocked from the /blocklist endpoint: ';
+        errorMsg = 'Received invalid blocked from the server: ';
         errorMsg = errorMsg + total;
         console.error(errorMsg);
         reject({reason: errorMsg});
@@ -62,7 +87,7 @@ function getBlocklist(uri) {
     };
 
     request.ontimeout = function() {
-      reject({reason: 'the blocklist HTTP request timed out'});
+      reject({reason: 'the uriinfo HTTP request timed out'});
     };
 
     settings.then(function(settings) {
@@ -76,27 +101,13 @@ function getBlocklist(uri) {
 }
 
 /**
-  * Make an HTTP request to the /blocklist endpoint and return a Promise that
-  * resolves to the value of the response.
-  *
-  * This function can be called with the same uri multiple times consecutively
-  * and it'll just keep returning the same Promise - won't make multiple HTTP
-  * requests.
-  *
-  * But if you call the function with a different uri, then call it with the
-  * first uri again, then it _will_ make another request for the first uri.
-  *
-  * Return a rejected Promise if the HTTP request times out, fails or is
-  * invalid for any reason.
-  *
-  * Return a rejected Promise is the given uri is undefined.
+  * Return getBlocklist(uri) only if:
   *
-  * @param {String} uri The URI to be checked
-  * @returns {Promise} A Promise that resolves to an object with three
-  *   properties:
+  * - this is the first time we're calling getBlocklist() with any uri, or
+  * - the previous time we called getBlocklist() it was with a different uri
   *
-  *   1. total: the number of annotations there are of this URI (Number)
-  *   2. blocked: whether or not this URI is blocklisted (Boolean)
+  * otherwise just return the result from the previous time we called
+  * getBlocklist(uri), which was with the same uri.
   *
   */
 function getBlocklistIfUriHasChanged(uri) {