Documentation fixes.

README.md

@@ -1,6 +1,8 @@
 ## redfour
 
-A small library that implements a binary semaphore using Redis.
+A small library that implements a binary semaphore using Redis. This is useful if you'd like to restrict access to one part of your code such that only one resource (the one with the lock) can access it at a time. Then, if another resource wants to access it, it will have to wait until the first resource is finished.
+
+For example, say you have code that checks to see if an access token is expired, and then if it is, refreshes it. You don't want two parallel processes trying to check for expiration - both will consider the token expired and refresh at the same time. Instead, you can use this module to ensure only one resource has access to that codepath at a time.
 
 ## Install
 

src/index.js

@@ -51,16 +51,15 @@ Object.assign(Lock.prototype, {
    * Acquire a lock for a specific ID value. Callback returns the following value:
    *
    *   {
-   *     id: id of lock
    *     success: either true (lock was acquired) of false (lock was not aquired)
-   *     index: modification index for current lock
    *     ttl: expiration time for the lock
    *   }
    *
    * Lock index is a shared incrementing number (signed 64bit) that should ensure rogue
    * lock holders would not be able to mess with newer locks for the same resource.
    *
-   * @param {String} id Identifies the lock
+   * @param {String} id Identifies the lock. This is an arbitrary string that should be consistent among 
+   *    different processes trying to acquire this lock.
    * @param {Number} ttl Automatically release lock after TTL (ms). Must be positive integer
    * @param {Function} done Callback
    */
@@ -109,7 +108,6 @@ Object.assign(Lock.prototype, {
    * Callback returns the following value:
    *
    *   {
-   *     id: id of lock
    *     success: either true (lock was released or did not exist) of false (lock was not released)
    *     result: status text. Either 'expired', 'released' or 'conflict'
    *   }
@@ -157,13 +155,12 @@ Object.assign(Lock.prototype, {
    * up to {waitTtl} milliseconds before giving up. The callback returns the following values:
    *
    *   {
-   *     id: id of lock
    *     success: either true (lock was acquired) of false (lock was not aquired by given ttl)
-   *     index: modification index for current lock
    *     ttl: expiration time for the lock
    *   }
    *
-   * @param {String} id Identifies the lock
+   * @param {String} id Identifies the lock. This is an arbitrary string that should be consistent among 
+   *    different processes trying to acquire this lock.
    * @param {Number} ttl Automatically release acquired lock after TTL (ms). Must be positive integer
    * @param {Number} waitTtl Give up until ttl (in ms) or wait indefinitely if value is 0
    * @param {Function} done Callback