Clarify comments.

Author: jaredhanson

lib/state/session.js

@@ -1,18 +1,19 @@
 var uid = require('uid2');
 
 /**
- * Creates an instance of `SessionStateProvider`.
+ * Creates an instance of `SessionStore`.
  *
- * This is the default state provider implementation for the OAuth2Strategy.
- * If generates a random state and stores it in `req.session` under the `key`
- * provided in the constructor.
+ * This is the state store implementation for the OAuth2Strategy used when
+ * the `state` option is enabled.  It generates a random state and stores it in
+ * `req.session` and verifies it when the service provider redirects the user
+ * back to the application.
  *
- * If no session exists, the provider will throw an error. If you are not using
- * sessions, consider using `TokenStateProvider` instead.
+ * This state store requires session support.  If no session exists, an error
+ * will be thrown.
  *
  * Options:
  *
- *   - `key`               The key in the session under which to store the session state
+ *   - `key`  The key in the session under which to store the state
  *
  * @constructor
  * @param {Object} options
@@ -24,10 +25,11 @@ function SessionStore(options) {
 }
 
 /**
- * Given a request, returns a value to use as state.
+ * Store request state.
  *
- * This implementation simply generates a random UID and stores the value in the session
- * for validation at a later stage when `verify` is called.
+ * This implementation simply generates a random string and stores the value in
+ * the session, where it will be used for verification when the user is
+ * redirected back to the application.
  *
  * @param {Object} req
  * @param {Function} callback
@@ -44,15 +46,10 @@ SessionStore.prototype.store = function(req, callback) {
 };
 
 /**
- * Given a request, and the state returned by the OAuth provider, verifies the state.
+ * Verify request state.
  *
- * This implementation simply compares the returned state to the one saved in the user's session.
- * If they do not match, or no state is saved in the session, the call will fail.
- * If there is no session, the call will return an error.
- *
- * The callback signature has two values (`err`, `failureCode`). On success, these are both
- * undefined. On error, only `err` is definied and on failure, err will contain the failure object
- * while `failureCode` will contain the failure code.
+ * This implementation simply compares the state parameter in the request to the
+ * value generated earlier and stored in the session.
  *
  * @param {Object} req
  * @param {String} providedState
@@ -84,7 +81,5 @@ SessionStore.prototype.verify = function(req, providedState, callback) {
   return callback(null, true);
 };
 
-/**
- * Expose `SessionStateProvider`.
- */
+// Expose constructor.
 module.exports = SessionStore;