From a5138b73886a33e900161c8c8984cdd30b24e2fe Mon Sep 17 00:00:00 2001 From: Bryan Donovan Date: Sun, 17 May 2015 14:23:22 -0700 Subject: [PATCH] adding jsdocs support --- .gitignore | 1 + Makefile | 5 ++++- README.md | 5 +++++ index.js | 8 +------- lib/caching.js | 49 ++++++++++++++++++++++++++++++++++++++++---- lib/index.js | 11 ++++++++++ lib/multi_caching.js | 17 ++++++++++++++- package.json | 1 + 8 files changed, 84 insertions(+), 13 deletions(-) create mode 100644 lib/index.js diff --git a/.gitignore b/.gitignore index 8d823bc..0f4cdf9 100644 --- a/.gitignore +++ b/.gitignore @@ -2,3 +2,4 @@ node_modules coverage .idea *.iml +out diff --git a/Makefile b/Makefile index 4d45a4d..7f53da8 100644 --- a/Makefile +++ b/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 diff --git a/README.md b/README.md index ce28fb7..4c61517 100644 --- a/README.md +++ b/README.md @@ -242,6 +242,11 @@ var multiCache = cacheManager.multiCaching([memoryCache, someOtherCache], { ``` +## Docs + +To generate JSDOC 3 documentation: + + make docs ## Tests diff --git a/index.js b/index.js index 7f57f84..bb0a047 100644 --- a/index.js +++ b/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'); diff --git a/lib/caching.js b/lib/caching.js index 1681201..90ce10d 100644 --- a/lib/caching.js +++ b/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); } diff --git a/lib/index.js b/lib/index.js new file mode 100644 index 0000000..b6c2ab1 --- /dev/null +++ b/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; diff --git a/lib/multi_caching.js b/lib/multi_caching.js index 1cb0f12..55164c8 100644 --- a/lib/multi_caching.js +++ b/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 diff --git a/package.json b/package.json index 0c0e145..5e6438e 100644 --- a/package.json +++ b/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",