adding jsdocs support

Author: BryanDonovan

.gitignore

@@ -2,3 +2,4 @@ node_modules
 coverage
 .idea
 *.iml
+out

Makefile

@@ -3,7 +3,7 @@ BASE = .
 ISTANBUL = ./node_modules/.bin/istanbul
 COVERAGE_OPTS = --lines 99 --statements 95 --branches 90 --functions 95
 
-main: lint test
+main: lint test docs
 
 cover:
 	$(ISTANBUL) cover test/run.js
@@ -28,5 +28,8 @@ lint:
 	./node_modules/.bin/jshint ./test --config $(BASE)/.jshintrc
 	./node_modules/.bin/jshint ./examples --config $(BASE)/.jshintrc
 
+docs:
+	./node_modules/.bin/jsdoc lib --recurse --readme README.md --package package.json
+	echo docs available in ./out/index.html
 
 .PHONY: test

README.md

@@ -242,6 +242,11 @@ var multiCache = cacheManager.multiCaching([memoryCache, someOtherCache], {
 
 ```
 
+## Docs 
+
+To generate JSDOC 3 documentation:
+
+    make docs
 
 ## Tests
 

index.js

@@ -1,7 +1 @@
-var cache = {
-    caching: require('./lib/caching'),
-    multi_caching: require('./lib/multi_caching'), //backward compat
-    multiCaching: require('./lib/multi_caching')
-};
-
-module.exports = cache;
+module.exports = require('./lib');

lib/caching.js

@@ -1,3 +1,4 @@
+/** @module cacheManager/caching */
 /*jshint maxcomplexity:15*/
 var domain = require('domain');
 var CallbackFiller = require('./callback_filler');
@@ -6,9 +7,7 @@ var CallbackFiller = require('./callback_filler');
  * Generic caching interface that wraps any caching library with a compatible interface.
  *
  * @param {object} args
- * @param {object|string} args.store - The store must have at least the following functions:
- *   - set
- *   - get
+ * @param {object|string} args.store - The store must at least have `set` and a `get` functions.
  * @param {function} [args.isCacheableValue] - A callback function which is called
  *   with every value returned from cache or from a wrapped function. This lets you specify
  *   which values should and should not be cached. If the function returns true, it will be
@@ -48,8 +47,15 @@ var caching = function(args) {
      * its results are stored in cache so subsequent calls retrieve from cache
      * instead of calling the function.
      *
-     * @example
+     * @function
+     * @name wrap
+     *
+     * @param {string} key - The cache key to use in cache operations
+     * @param {function} work - The function to wrap
+     * @param {object} [options] - options passed to `set` function
+     * @param {function} cb
      *
+     * @example
      *   var key = 'user_' + userId;
      *   cache.wrap(key, function(cb) {
      *       User.get(userId, cb);
@@ -100,26 +106,61 @@ var caching = function(args) {
         });
     };
 
+    /**
+     * Binds to the underlying store's `get` function.
+     * @function
+     * @name get
+     */
     self.get = self.store.get.bind(self.store);
 
+    /**
+     * Binds to the underlying store's `set` function.
+     * @function
+     * @name set
+     */
     self.set = self.store.set.bind(self.store);
 
+    /**
+     * Binds to the underlying store's `del` function if it exists.
+     * @function
+     * @name del
+     */
     if (typeof self.store.del === 'function') {
         self.del = self.store.del.bind(self.store);
     }
 
+    /**
+     * Binds to the underlying store's `setex` function if it exists.
+     * @function
+     * @name setex
+     */
     if (typeof self.store.setex === 'function') {
         self.setex = self.store.setex.bind(self.store);
     }
 
+    /**
+     * Binds to the underlying store's `reset` function if it exists.
+     * @function
+     * @name reset
+     */
     if (typeof self.store.reset === 'function') {
         self.reset = self.store.reset.bind(self.store);
     }
 
+    /**
+     * Binds to the underlying store's `keys` function if it exists.
+     * @function
+     * @name keys
+     */
     if (typeof self.store.keys === 'function') {
         self.keys = self.store.keys.bind(self.store);
     }
 
+    /**
+     * Binds to the underlying store's `ttl` function if it exists.
+     * @function
+     * @name ttl
+     */
     if (typeof self.store.ttl === 'function') {
         self.ttl = self.store.ttl.bind(self.store);
     }

lib/index.js

@@ -0,0 +1,11 @@
+/** @namespace cacheManager */
+var cacheManager = {
+    caching: require('./caching'),
+    // Deprecate
+    //jscs:disable requireCamelCaseOrUpperCaseIdentifiers
+    multi_caching: require('./multi_caching'), //backward compat
+    //jscs:enable requireCamelCaseOrUpperCaseIdentifiers
+    multiCaching: require('./multi_caching')
+};
+
+module.exports = cacheManager;

lib/multi_caching.js

@@ -1,10 +1,13 @@
+/** @module cacheManager/multiCaching */
 var async = require('async');
 var domain = require('domain');
 var CallbackFiller = require('./callback_filler');
 
 /**
- *
  * Module that lets you specify a hierarchy of caches.
+ *
+ * @memberof cacheManager
+ *
  * @param {array} caches - Array of caching objects.
  * @param {object} [options]
  * @param {function} [options.isCacheableValue] - A callback function which is called
@@ -177,6 +180,10 @@ var multiCaching = function(caches, options) {
 
     /**
      * Set value in all caches
+     *
+     * @function
+     * @name set
+     *
      * @param {string} key
      * @param {*} value
      * @param {object} [options] to pass to underlying set function.
@@ -196,6 +203,10 @@ var multiCaching = function(caches, options) {
 
     /**
      * Get value from highest level cache that has stored it.
+     *
+     * @function
+     * @name get
+     *
      * @param {string} key
      * @param {object} [options] to pass to underlying get function.
      * @param {function} cb
@@ -210,6 +221,10 @@ var multiCaching = function(caches, options) {
 
     /**
      * Delete value from all caches.
+     *
+     * @function
+     * @name del
+     *
      * @param {string} key
      * @param {object} [options] to pass to underlying del function.
      * @param {function} cb

package.json

@@ -27,6 +27,7 @@
     "coveralls": "^2.3.0",
     "istanbul": "^0.2.11",
     "jscs": "^1.9.0",
+    "jsdoc": "^3.3.0",
     "jshint": "^2.5.4",
     "mocha": "^1.20.1",
     "optimist": "^0.6.1",