Tidy up the code organization and documentation

README.md

@@ -24,7 +24,7 @@ var d = c.map(function (x) { return x + 1; }); // some(42)
 
 ## Documentation
 
-### contains(xs, x)
+### array.contains(xs, x)
 
 `contains` takes an array and an element, and returns whether the element
 exists at least once in the array.
@@ -36,7 +36,7 @@ var yep  = contains([1,2,3], 2); // true
 var nope = contains([1,2,3], 4); // false
 ```
 
-### compose(f, g)
+### fn.compose(f, g)
 
 [*demo*](http://jsfiddle.net/earldouglas/8q1znL7n/)
 
@@ -67,7 +67,7 @@ var five = compose(inc, square)(2); // inc(square(2)) == (2 ^ 2) + 1
 
 **g**: `function`, a unary function
 
-### curry(f, args)
+### fn.curry(f, args)
 
 `curry` takes an n-ary function `f` and an optional array of arguments, and
 returns a curried version of `f`, comprised of *n* nested unary functions
@@ -100,7 +100,7 @@ var fortyTwo = curry(mathemagic)(2)(20)(1);
 
 **args**: `array`, [optional] arguments to apply to `f`
 
-### memoize(f, cache)
+### fn.memoize(f, cache)
 
 `memoize` takes a function and an optional cache implementation, and
 memoizes the function by backing it with the cache, if supplied, or a simple
@@ -123,7 +123,7 @@ var fastResult = cheapFn(42); // cheap cache lookup the second time
 
 **cache**: `object`, [optional] a cache object with get(k) and put(k,v) functions
 
-### lazy(f, cache)
+### fn.lazy(f, cache)
 
 `lazy` takes a function and an optional cache implementation, and creates a
 function that, given input arguments, returns a lazy evaluator that will
@@ -188,7 +188,7 @@ An option instance exposes the following fields:
 
 **value**: `any`, [optional] the value to wrap in an option
 
-### collect(promises, callback)
+### promise.collect(promises, callback)
 
 Given an array of promises and a callback, passes the result of each promise
 (in order) as an argument to the callback, and returns a single promise that
@@ -217,7 +217,7 @@ p is congruent to `Promise.resolve(2 * (20 + 1))`, or `Promise.resolve(42)`
 
 **callback**: `function`, a function that takes as arguments the results of the promises
 
-### valid(value)
+### validation.valid(value)
 
 `valid` constructs a "validation" representing a valid value.
 
@@ -234,7 +234,7 @@ A validation created by `valid` exposes the following fields:
 
 **value**: `any`, a valid value to wrap in a validation
 
-### invalid(errors)
+### validation.invalid(errors)
 
 `invalid` constructs a "validation" representing an invalid value, and
 containing an array of errors.

lib/function.js

@@ -1,70 +1,11 @@
 'use strict';
 
-/**
- *
- * [*demo*](http://jsfiddle.net/earldouglas/8q1znL7n/)
- *
- * `compose` takes two unary functions `f` and `g`, and combines them into a
- * single unary function `f ∘ g` that applies `g` to an input, passes the
- * output to `f`, applies `f` to it, and returns the result.
- *
- * The application of `(f ∘ g)(x)` is equivalent to `f(g(x))`.
- *
- * *Example:*
- *
- * ```javascript
- * function inc(x) {
- *   return x + 1;
- * }
- *
- * function square(x) {
- *   return x * x;
- * }
- *
- * var nine = compose(square, inc)(2); // square(inc(2)) == (2 + 1) ^ 2
- * var five = compose(inc, square)(2); // inc(square(2)) == (2 ^ 2) + 1
- * ```
- *
- * @param f {function} a unary function
- * @param g {function} a unary function
- *
- */
 function compose(f, g) {
   return function (x) {
     return f(g(x));
   };
 }
 
-/**
- * `curry` takes an n-ary function `f` and an optional array of arguments, and
- * returns a curried version of `f`, comprised of *n* nested unary functions
- * where the arity of `f` is *n*.
- *
- * *Example:*
- *
- * ```javascript
- * function add(x, y) {
- *   return x + y;
- * };
- *
- * var add2 = curry(add)(2);
- * var five = add2(3);
- * ```
- *
- * *Example:*
- *
- * ```javascript
- * function mathemagic(x, y, z) {
- *   return x * (y + z);
- * };
- *
- * var fortyTwo = curry(mathemagic)(2)(20)(1);
- * ```
- *
- * @param f {function} an n-ary function
- * @param args {array} [optional] arguments to apply to `f`
- *
- */
 function curry(f, args) {
   if (!args || !args.length) {
     args = [];
@@ -87,26 +28,6 @@ function dumbCache() {
   };
 }
 
-/**
- * `memoize` takes a function and an optional cache implementation, and
- * memoizes the function by backing it with the cache, if supplied, or a simple
- * object-based cache otherwise.
- *
- * *Example:*
- *
- * ```javascript
- * function expensiveFn(n) { ... }
- *
- * var cheapFn = memoize(expensiveFn);
- *
- * var slowResult = cheapFn(42); // expensive computation the first time
- * var fastResult = cheapFn(42); // cheap cache lookup the second time
- * ```
- *
- * @param f {function} an n-ary function
- * @param cache {object} [optional] a cache object with get(k) and put(k,v) functions
- *
- */
 function memoize(f, cache) {
   if (!cache) {
     cache = dumbCache();
@@ -124,27 +45,6 @@ function memoize(f, cache) {
   };
 }
 
-/**
- * `lazy` takes a function and an optional cache implementation, and creates a
- * function that, given input arguments, returns a lazy evaluator that will
- * apply the function to the arguments only when needed, and only once if
- * needed many times.
- *
- * *Example:*
- *
- * ```javascript
- * function expensiveFn(n) { ... }
- *
- * var lazyVal = lazy(expensiveFn)(42); // lazily apply 42 -- no computation yet
- *
- * var slowResult = lazyVal.get(); // expensive computation the first time
- * var fastResult = lazyVal.get(); // cheap cache lookup the second time
- * ```
- *
- * @param f {function} an n-ary function
- * @param cache {object} [optional] a cache object with get(k) and put(k,v) functions
- *
- */
 function lazy(f, cache) {
   var fMemo = memoize(f, cache);
   return function() {

lib/list.js

@@ -20,26 +20,6 @@ function _cons(head, tail) {
   };
 }
 
-/**
- * `list` constructs a linked list from a value, `head`, representing the first
- * element in the list, and another list, `tail`, representing the rest of the
- * constructed list. If `head` is null, `tail` is returned, and if `tail` is
- * null, the empty list is returned.
- *
- * A list instance exposes the following fields:
- *
- *  * `head` - the head of this list, if it is not empty
- *  * `tail` - the tail of this list, if it is not empty
- *  * `length` - returns the length of this list
- *  * `map(f)` - returns a new list created by applying `f` over this list
- *  * `flatMap(f)` - returns a new list created by applying `f` over this list and concatenating the results
- *  * `concat(l)` - returns the concatenation of this list with l
- *  * `toString()`
- *
- * @param head {any} the first element in the list
- * @param tail {list} the rest of the list
- *
- */
 function list(head, tail) {
   if (tail == null) {
     return list(head, _nil);
@@ -50,4 +30,4 @@ function list(head, tail) {
   }
 }
 
-exports.list = list;
+module.exports = list;

lib/option.js

@@ -1,21 +1,5 @@
 'use strict';
 
-/**
- * `option` constructs a representation of an optional value, represented as
- * either "some value" or "no value", depending on whether a non-null argument
- * was supplied.
- *
- * An option instance exposes the following fields:
- *
- * * `empty`
- * * `map(f)` - returns a new option by applying `f` over this option's value, and wrapping the result in an option
- * * `flatMap(f)` - returns a new option by applying `f` over this option's value, and returning the result
- * * `ap(a)` - assumes this option wraps a function, and returns a new option by mapping this option's function over the option `a` and returning the result
- * * `toString()`
- *
- * @param value {any} [optional] the value to wrap in an option
- *
- */
 function option(value) {
   if (value != null) {
     return {
@@ -36,4 +20,4 @@ function option(value) {
   }
 }
 
-exports.option = option;
+module.exports = option;

lib/promise.js

@@ -2,32 +2,6 @@
 
 var curry = require('./function').curry;
 
-/**
- * Given an array of promises and a callback, passes the result of each promise
- * (in order) as an argument to the callback, and returns a single promise that
- * yields the result of the callback.
- *
- * Any of the promises can be 'lazy', implemented as a nullary function that 
- * returns a promise, and will be retrieved as late as possible.
- *
- * *Example:*
- *
- * ```javascript
- * var p = collect([
- *   Promise.resolve(2),
- *   Promise.resolve(20),
- *   Promise.resolve(1)
- * ], function (x, y, z) {
- *   return x * (y + z);
- * });
- * ```
- *
- * p is congruent to `Promise.resolve(2 * (20 + 1))`, or `Promise.resolve(42)`
- *
- * @param promises {array} an array of promises
- * @param callback {function} a function that takes as arguments the results of the promises
- *
- */
 function collect(promises, callback) {
     var f = curry(callback);
     var p = promises.reduce(function (p1, p2) {

lib/validation.js

@@ -1,20 +1,5 @@
 'use strict';
 
-/**
- * `valid` constructs a "validation" representing a valid value.
- *
- * A validation created by `valid` exposes the following fields:
- *
- * * `valid` - returns true
- * * `value` - returns the (valid) value
- * * `map(f) - returns a new (valid) validation by mapping `f` over this validation's value and wrapping the in a (valid) validation
- * * `flatMap(f) - returns a new validation result by mapping `f` over this validation's value and returning the result
- * * `ap(a)` - assumes this validation wraps a function, and returns a new validation by mapping this validation's function over the validation `a` and returning the result
- * * `toString()`
- *
- * @param value {any} a valid value to wrap in a validation
- *
- */
 function valid(value) {
   return {
     valid    : true,
@@ -26,22 +11,6 @@ function valid(value) {
   };
 }
 
-/**
- * `invalid` constructs a "validation" representing an invalid value, and
- * containing an array of errors.
- *
- * A validation created by `invalid` exposes the following fields:
- *
- * * `valid` - returns false
- * * `errors` - returns the array of errors
- * * `map(f)` - returns a this validation
- * * `flatMap(f)` - returns this validation
- * * `ap(a)` - if `a` is valid, return this validation, otherwise returns a new (invalid) validation containing the concatenation of this validation's errors with `a`'s errors
- * * `toString()`
- *
- * @param errors {array} an array of errors to wrap in a validation
- *
- */
 function invalid(errors) {
   return {
     valid    : false,