Doc fixes (#599)

* Fix #584

* Clarify docs

src/auth/OAuthAuthenticator.js

@@ -354,26 +354,26 @@ OAuthAuthenticator.prototype.clientCredentialsGrant = function(options, cb) {
  *   </a>.
  * </caption>
  *
- * var data = {
+ * var options = {
  *   code: '{CODE}',
  *   redirect_uri: '{REDIRECT_URI}',
  *   client_id: '{CLIENT_ID}',  // Optional field.
  *   client_secret: '{CLIENT_SECRET}',  // Optional field.
  *   organization: '{ORGANIZATION_ID}' // Optiional field.
  * };
  *
- * auth0.oauth.authorizationCodeGrant(data, function (err, userData) {
+ * auth0.oauth.authorizationCodeGrant(options, function (err, userData) {
  *   if (err) {
  *     // Handle error.
  *   }
  *
  *   console.log(userData);
  * });
  *
- * @param   {Object}    data                  Authorization code payload
- * @param   {String}    userData.organization Organization ID
- * @param   {String}    userData.code         Code in URL returned after authentication
- * @param   {String}    userData.redirect_uri The URL to which Auth0 will redirect the browser after authorization has been granted by the user.
+ * @param   {Object}    options                  Authorization code payload
+ * @param   {String}    options.organization     Organization ID
+ * @param   {String}    options.code             Code in URL returned after authentication
+ * @param   {String}    options.redirect_uri     The URL to which Auth0 will redirect the browser after authorization has been granted by the user.
  *
  * @return  {Promise|undefined}
  */

src/auth/PasswordlessAuthenticator.js

@@ -60,14 +60,16 @@ var PasswordlessAuthenticator = function(options, oauth) {
  * @method    signIn
  * @memberOf  module:auth.PasswordlessAuthenticator.prototype
  * @example <caption>
- *   Given the user credentials (`phone_number` and `code`), it will do the
- *   authentication on the provider and return a JSON with the `access_token`
- *   and `id_token` using `/oauth/ro` endpoint.
+ * Once you have a verification code, use this endpoint to login
+ * the user with their phone number/email and verification code.
+ *
+ * https://auth0.com/docs/api/authentication#authenticate-user
  * </caption>
  *
  * var data = {
- *   username: '{PHONE_NUMBER}',
- *   password: '{VERIFICATION_CODE}'
+ *   username: '{PHONE_NUMBER OR EMAIL}',
+ *   otp: '{VERIFICATION_CODE}',
+ *   realm: '{sms or email}' // OPTIONAL DEFAULTS TO SMS
  * };
  *
  * auth0.passwordless.signIn(data, function (err) {
@@ -77,12 +79,27 @@ var PasswordlessAuthenticator = function(options, oauth) {
  * });
  *
  * @example <caption>
- * To use `/oauth/token` endpoint, use `otp` and `realm` instead
+ *   The user data object has the following structure.
+ * </caption>
+ *
+ * {
+ *   id_token: String,
+ *   access_token: String,
+ *   token_type: String
+ * }
+ *
+ * @example <caption>
+ *  LEGACY signIn using the `/oauth/ro` endpoint. When otp is not specified
+ *  password is required. Given the user credentials (`phone_number` and `code`),
+ *  it will do the authentication on the provider and return a JSON with
+ *  the `access_token` and `id_token`.
+ *
+ * https://auth0.com/docs/api/authentication#resource-owner
  * </caption>
  *
  * var data = {
  *   username: '{PHONE_NUMBER}',
- *   otp: '{VERIFICATION_CODE}'
+ *   password: '{VERIFICATION_CODE}'
  * };
  *
  * auth0.passwordless.signIn(data, function (err) {
@@ -91,21 +108,11 @@ var PasswordlessAuthenticator = function(options, oauth) {
  *   }
  * });
  *
- * @example <caption>
- *   The user data object has the following structure.
- * </caption>
- *
- * {
- *   id_token: String,
- *   access_token: String,
- *   token_type: String
- * }
- *
  * @param   {Object}    userData              User credentials object.
- * @param   {String}    userData.otp          The user's verification code.
- * @param   {String}    [userData.realm=sms]  Realm string: "sms" or "email".
  * @param   {String}    userData.username     The user's phone number if realm=sms, or the user's email if realm=email
- * @param   {String}    userData.password     [DEPRECATED] Password.
+ * @param   {String}    userData.otp        The user's verification code. Required
+ * @param   {String}    [userData.realm=sms]  Realm string: "sms" or "email".
+ * @param   {String}    [userData.password]     [DEPRECATED] Password required if using legacy /oauth/ro endpoint
  * @param   {String}    [userData.connection=sms] [DEPRECATED] Connection string: "sms" or "email".
  * @param   {Object}    [options]              Additional options.
  * @param   {String}    [options.forwardedFor] Value to be used for auth0-forwarded-for header

src/auth/TokensManager.js

@@ -4,7 +4,7 @@ var axios = require('axios');
 var ArgumentError = require('rest-facade').ArgumentError;
 
 /**
- * @class
+ * @class TokensManager
  * Provides methods for getting token data and exchanging tokens.
  * @constructor
  * @memberOf module:auth
@@ -33,7 +33,7 @@ var TokensManager = function(options) {
 /**
  * Given an ID token get the user profile linked to it.
  *
- * @method
+ * @method   getInfo
  * @memberOf module:auth.TokensManager.prototype
  *
  * @example <caption>
@@ -88,7 +88,7 @@ TokensManager.prototype.getInfo = function(idToken, cb) {
  * Exchange the token of the logged in user with a token that is valid to call
  * the API (signed with the API secret).
  *
- * @method
+ * @method   getDelegationToken
  * @memberOf module:auth.TokensManager.prototype
  *
  * @example <caption>
@@ -177,7 +177,7 @@ TokensManager.prototype.getDelegationToken = function(data, cb) {
 /**
  * Proactively revoke an issued refresh token.
  *
- * @method
+ * @method   revokeRefreshToken
  * @memberOf module:auth.TokensManager.prototype
  *
  * @example <caption>

src/auth/UsersManager.js

@@ -4,7 +4,7 @@ var axios = require('axios');
 var ArgumentError = require('rest-facade').ArgumentError;
 
 /**
- * @class
+ * @class UsersManager
  * Provides methods for getting user information and impersonating users.
  * @constructor
  * @memberOf module:auth

src/auth/index.js

@@ -41,7 +41,6 @@ var BASE_URL_FORMAT = 'https://%s';
  * @param   {String}  options.domain                    AuthenticationClient server domain.
  * @param   {String}  [options.clientId]                Default client ID.
  * @param   {String}  [options.clientSecret]            Default client Secret.
- * @param   {String}  [options.organization]            Organization ID.
  * @param   {String}  [options.supportedAlgorithms]     Algorithms that your application expects to receive
  * @param  {Boolean}  [options.__bypassIdTokenValidation] Whether the id_token should be validated or not
  * @param   {Object}  [options.headers]                 Additional headers that will be added to the outgoing requests.