Readme and docs update

README.md

@@ -4,25 +4,28 @@
 
 ## Installation
 
+When its on npm...
+
 ```sh
 npm install hyacinth
 ```
 
 ## Usage
 
 ```js
-var TokenBucket = require('token-bucket-rate-limiter');
+var TokenBucket = require('hyacinth');
 
 var rateLimiter = new TokenBucket({
 	redis: redisClient,
 	poolMax: 250,
 	fillRate: 240,
-	identifier: 'api-token-bucket-'
 });
 
-rateLimiter.rateLimitWithRedis(testKey, 10).then(function(data){
-	if(!data) return requestDenied();
+rateLimiter.rateLimit(testKey, 10).then(function(tokensRemaining){
+    // Negative number indicates the tokens remaining but limited
+    // as the cost was higher than those remaining
 
+	if(data < 0) return requestDenied();
 	requestApproved();
 });
 ```

lib/TokenBucket.js

@@ -6,10 +6,9 @@ var Redis = require('redis');
 var Scripty = require('node-redis-scripty');
 
 /**
- * Constructor for TokenBucket accepts an object with config containing either
- * a node-redis client or the config to set up the client
- * @param {Object} [config] - The configuration object for the TokenBucket
- * @param {Object} [config.redis] - The redis client to be used as the store
+ * Constructor for TokenBucket
+ * @param {Object} config - The configuration object for the TokenBucket
+ * @param {Object} config.redis - The redis client to be used as the store
  * @param {number} [config.poolMax=250] - The maximum size of the token pool
  * @param {number} [config.fillRate=240] - The rate in milliseconds that the
  * pool will be refilled
@@ -57,7 +56,8 @@ TokenBucket.prototype.clearRateLimitWithKey = function(key, cb) {
  * @param  {string}   key  The key to be rate limited
  * @param  {number}   cost The cost of the operation
  * @param  {Function} cb   The callback function
- * @return {Promise}       The promise object for this operation
+ * @return {Promise.<number, Error>} - Resolves to the number of tokens left with
+ *                              a negative number indicating that the req was limited
  */
 TokenBucket.prototype.rateLimit = function(key, cost, cb) {
   var self = this;
@@ -116,7 +116,7 @@ TokenBucket.prototype.rateLimit = function(key, cost, cb) {
  * @param  {string}   key  The key to be rate limited
  * @param  {number}   cost The cost of the operation
  * @param  {Function} cb   The callback function
- * @return {Promise}       The promise object for this operation
+ * @return {Promise.<number,Error}       The promise object for this operation
  */
 TokenBucket.prototype.rateLimitWithoutLua = function(key, cost, cb) {
   var self = this;