📚 docs(src): Improve function documentation.

Author: make-github-pseudonymous-again

src/native/decreasing.js

@@ -1,3 +1,9 @@
-
+/**
+ * Compare two objects in decreasing order using the native comparison and
+ * equality operators.
+ *
+ * @param {Object} a - The first parameter.
+ * @param {Object} b - The second parameter.
+ * @return {Number} -1 if a > b, 0 if a === b, and 1 otherwise.
+ */
 export const decreasing = ( a , b ) => ( a > b ) ? -1 : ( a === b ) ? 0 : 1 ;
-

src/native/increasing.js

@@ -1,3 +1,9 @@
-
+/**
+ * Compare two objects in increasing order using the native comparison and
+ * equality operators.
+ *
+ * @param {Object} a - The first parameter.
+ * @param {Object} b - The second parameter.
+ * @return {Number} -1 if a < b, 0 if a === b, and 1 otherwise.
+ */
 export const increasing = ( a , b ) => ( a < b ) ? -1 : ( a === b ) ? 0 : 1 ;
-

src/proxy/attr/attr.js

@@ -1,4 +1,9 @@
-
+/**
+ * Generates a binary attribute comparator
+ * from a binary comparator and an attribute key.
+ *
+ * @param {Function} compare - The function used to order attributes.
+ * @param {Object} key - The key of the attribute used in the comparison.
+ * @return {Function} The function that orders objects by attribute.
+ */
 export const attr = ( compare , key ) => ( a , b ) => compare( a[key] , b[key] ) ;
-
-

src/proxy/attr/len.js

@@ -1,3 +1,8 @@
-
+/**
+ * Generates a binary length comparator
+ * from a binary comparator.
+ *
+ * @param {Function} compare - The function used to order lengths.
+ * @return {Function} The function that orders objects by length.
+ */
 export const len = compare => ( a , b ) => compare( a.length , b.length ) ;
-

src/proxy/fn.js

@@ -1,3 +1,9 @@
-
+/**
+ * Generates a binary comparator
+ * from a binary comparator and a function.
+ *
+ * @param {Function} compare - The function used to order values.
+ * @param {Function} callable - The function that generates values used in the comparison.
+ * @return {Function} The function that orders objects by value.
+ */
 export const fn = ( compare , callable ) => ( a , b ) => compare( callable( a ) , callable( b ) ) ;
-

src/tools/reverse.js

@@ -1,3 +1,7 @@
-
+/**
+ * Reverse the order of a comparator.
+ *
+ * @param {Function} compare - The comparator to reverse.
+ * @return {Function} A function f such that compare(a,b) === f(b,a) for all a,b.
+ */
 export const reverse = compare => ( a , b ) => compare( b , a ) ;
-

src/tools/sign.js

@@ -1,3 +1,7 @@
-
+/**
+ * Computes the sign of the input number.
+ *
+ * @param {Number} v - The number to compute the sign of.
+ * @return {Number} -1 if v < 0, 1 if v > 0, 0 otherwise.
+ */
 export const sign = v => v < 0 ? -1 : v > 0 ? 1 : 0 ;
-