From dea78333ffadf9d5dcd76b3cba7d146fa04ca0cf Mon Sep 17 00:00:00 2001
From: Aaron Jensen <aaronjensen@gmail.com>
Date: Wed, 19 Aug 2015 07:29:06 -0700
Subject: [PATCH] Add some jsdoc

---
 lib/constant.js | 38 ++++++++++++++++++++++++++++++++++++--
 lib/freeze.js   | 15 ++++++++++++++-
 lib/update.js   |  2 ++
 3 files changed, 52 insertions(+), 3 deletions(-)

diff --git a/lib/constant.js b/lib/constant.js
index 0a439b2..f4e6bec 100644
--- a/lib/constant.js
+++ b/lib/constant.js
@@ -1,6 +1,40 @@
 import freeze from './freeze';
 
-export default function constant(object) {
-  const frozen = freeze(object);
+/**
+ * Returns a function that always returns the supplied value.
+ *
+ * Useful for replacing an object outright rather than merging it.
+ *
+ * @function
+ * @sig a -> (* -> a)
+ * @memberOf u
+ * @param  {*} value what to return from returned function.
+ * @return {function} a new function that will always return value.
+ *
+ * @example
+ * var alwaysFour = u.constant(4);
+ * expect(alwaysFour(32)).toEqual(4);
+ *
+ * @example
+ * var user = {
+ *   name: 'Mitch',
+ *   favorites: {
+ *     band: 'Nirvana',
+ *     movie: 'The Matrix'
+ *   }
+ * };
+ *
+ * var newFavorites = {
+ *   band: 'Coldplay'
+ * };
+ *
+ * var result = u({ favorites: u.constant(newFavorites) }, user);
+ *
+ * expect(result).toEqual({ name: 'Mitch', favorites: { band: 'Coldplay' } });
+ */
+function constant(value) {
+  const frozen = freeze(value);
   return () => frozen;
 }
+
+export default constant;
diff --git a/lib/freeze.js b/lib/freeze.js
index 361d057..8d88d80 100644
--- a/lib/freeze.js
+++ b/lib/freeze.js
@@ -22,7 +22,18 @@ function recur(object) {
   return object;
 }
 
-export default function freeze(object) {
+/**
+ * Deeply freeze a plain javascript object.
+ *
+ * If `process.env.NODE_ENV === 'production'`, this returns the original object
+ * witout freezing.
+ *
+ * @function
+ * @sig a -> a
+ * @param  {object} object Object to freeze.
+ * @return {object} Frozen object, unless in production, then the same object.
+ */
+function freeze(object) {
   if (process.env.NODE_ENV === 'production') {
     return object;
   }
@@ -33,3 +44,5 @@ export default function freeze(object) {
 
   return object;
 }
+
+export default freeze;
diff --git a/lib/update.js b/lib/update.js
index 7927524..5ea4e62 100644
--- a/lib/update.js
+++ b/lib/update.js
@@ -49,6 +49,8 @@ function updateArray(updates, object) {
  * update({ foo: x => (x + 1) }, { foo: 2 });
  * // => { foo: 3 }
  *
+ * @function
+ * @name update
  * @param {Object|Function} updates
  * @param {Object|Array}    object to update
  * @return {Object|Array}   new object with modifications