diff --git a/common/content/util.js b/common/content/util.js index 411c3dd2..475ff3c1 100644 --- a/common/content/util.js +++ b/common/content/util.js @@ -34,9 +34,21 @@ default xml namespace = XHTML; const util = { //{{{ + /** + * Array utility methods. + * @singleton + */ Array: { - // [["a", "b"], ["c", "d"]] -> { a: "b", c: "d" } - // From Common Lisp, more or less + /** + * Converts an array to an object. As in lisp, an assoc is an + * array of key-value pairs, which maps directly to an object, + * as such: + * [["a", "b"], ["c", "d"]] -> { a: "b", c: "d" } + * + * @param {Array[]} assoc + * @... {string} 0 - Key + * @... 1 - Value + */ assocToObj: function assocToObj(assoc) { let obj = {}; @@ -44,9 +56,18 @@ const util = { //{{{ return obj; }, - // flatten an array: [["foo", ["bar"]], ["baz"], "quux"] -> ["foo", ["bar"], "baz", "quux"] + /** + * Flatten an array, such that all elements of the array are + * joined into a single array: + * [["foo", ["bar"]], ["baz"], "quux"] -> ["foo", ["bar"], "baz", "quux"] + */ flatten: function flatten(ary) Array.concat.apply([], ary), + /** + * Returns an Iterator for an array's values. + * + * @returns {Iterator(Object)} + */ iterator: function iterator(ary) { let length = ary.length; @@ -54,6 +75,11 @@ const util = { //{{{ yield ary[i]; }, + /** + * Returns an Iterator for the arrays indices and values. + * + * @returns {Iterator([{number}, {Object}])} + */ iterator2: function (ary) { let length = ary.length; @@ -61,6 +87,14 @@ const util = { //{{{ yield [i, ary[i]]; }, + /** + * Filters out all duplicates from an array. If + * unsorted is false, the array is sorted before + * duplicates are removed. + * + * @param {Array} ary + * @param {boolean} unsorted + */ uniq: function uniq(ary, unsorted) { let ret = []; @@ -83,6 +117,11 @@ const util = { //{{{ } }, + /** + * Returns a shallow copy of obj. + * + * @param {Object} obj + */ cloneObject: function cloneObject(obj) { if (obj instanceof Array) @@ -93,13 +132,35 @@ const util = { //{{{ return newObj; }, + /** + * Clips a string to a given length. If the input string is longer + * than length, an elipsis is appended. + * + * @param {string} str + * @param {number} length + * @returns {string} + */ clip: function clip(str, length) { return str.length <= length ? str : str.substr(0, length - 3) + "..."; }, + /** + * Compares two strings, case insensitively. Return values are as + * in String#localeCompare. + * + * @param {string} a + * @param {string} b + * @returns {number} + */ compareIgnoreCase: function compareIgnoreCase(a, b) String.localeCompare(a.toLowerCase(), b.toLowerCase()), + /** + * Returns an object representing a Node's computed CSS style. + * + * @param {Node} node + * @returns {Object} + */ computedStyle: function computedStyle(node) { while (node instanceof Text && node.parentNode)