update documentation for email_for_token call

lib/wsapi/email_for_token.js

@@ -7,10 +7,15 @@ db = require('../db.js'),
 httputils = require('../httputils.js'),
 logger = require('../logging.js').logger;
 
-/* First half of account creation.  Stages a user account for creation.
- * this involves creating a secret url that must be delivered to the
- * user via their claimed email address.  Upon timeout expiry OR clickthrough
- * the staged user account transitions to a valid user account
+/* Given a verification secret (a "token", delivered via email), return the
+ * email address associated with this token.
+ *
+ * This call also returns a hint to the UI, regarding whether completing the
+ * email verification that this token will require the user to enter their
+ * password.
+ *
+ * These two things are conflated into a single call as a performance
+ * optimization.
  */
 
 exports.method = 'get';