add documentation to the 'pack' library, to better explain the encoding technique used for telling content scripts which DOM methods should be blocked.

lib/pack.js

@@ -1,5 +1,20 @@
 /*jslint es6: true, for: true, bitwise: true*/
 /*global window*/
+// Functions to represent a selection of options out of a bigger set
+// in a compact, base64 representation.
+//
+// This is used in the extension to encode which Web API standards should
+// be blocked on the current domain, in a way that can be encoded in a cookie
+// value.
+//
+// The two exposed functions in this module are pack and unpack, which are
+// inverses of each other.  For example:
+//
+// const options = ["A", "B", "C"];
+// const selection = ["B", "C"];
+// const base64EncodedSelection = pack(options, selection);
+// const decodedSelection = unpack(options, base64EncodedSelection);
+// decodedSelection == selection // true
 (function () {
     "use strict";
 
@@ -38,6 +53,25 @@
         return prev;
     };
 
+    /**
+     * Encodes a selection of values, from a larger set of possible options,
+     * into a base64 encoded bitfield.
+     *
+     * The caller should make sure that selected is a subset of options.
+     *
+     * The ordering of options and selected do not matter.
+     *
+     * This function is the inverse of the `unpack` function from this module.
+     *
+     * @param array options
+     *   An array of all possible options that might need to be encoded.
+     * @param array selected
+     *   An array containing zero or more elements from option.
+     *
+     * @return string
+     *   A base64 encoded string, which encodes which elements in `options`
+     *   were in the provided `selected` array.
+     */
     const pack = function (options, selected) {
 
         const numBuckets = Math.ceil(options.length / bucketSize);
@@ -68,6 +102,24 @@
         return encodedString;
     };
 
+    /**
+     * Decodes a base64 encoded bitfield into an array of values, each of
+     * which are in the provided options array.
+     *
+     * The ordering of the options array does not matter.
+     *
+     * This function is the inverse of the `pack` function from this module.
+     *
+     * @param array options
+     *   An array of all possible options that might need to be encoded.
+     * @param string data
+     *   A base64 encoded string, generated from the `pack` function in
+     *   this module.
+     *
+     * @return array
+     *   An array of zero or more elements, each of which will be in the
+     *   options array.
+     */
     const unpack = function (options, data) {
 
         const binToBucketSizeFunc = binOptionsReduceFunction.bind(undefined, bucketSize);
@@ -99,4 +151,4 @@
         pack,
         unpack
     };
-}());
+}());