add javadocs to all classses

Author: lbalmaceda

.idea/compiler.xml

@@ -1,14 +1,19 @@
 package com.auth0.client.auth;
 
-import com.auth0.utils.Asserts;
 import com.auth0.json.auth.UserInfo;
 import com.auth0.net.*;
+import com.auth0.utils.Asserts;
 import com.fasterxml.jackson.core.type.TypeReference;
 import okhttp3.HttpUrl;
 import okhttp3.OkHttpClient;
 import okhttp3.logging.HttpLoggingInterceptor;
 import okhttp3.logging.HttpLoggingInterceptor.Level;
 
+/**
+ * Class that provides an implementation of some of the Authentication and Authorization API methods defined in https://auth0.com/docs/api/authentication.
+ * To begin create a new instance of {@link #AuthAPI(String, String, String)} using the tenant domain, client id and client secret.
+ */
+@SuppressWarnings("WeakerAccess")
 public class AuthAPI {
 
     private static final String KEY_CLIENT_ID = "client_id";
@@ -31,6 +36,13 @@ public class AuthAPI {
     private final TelemetryInterceptor telemetry;
     private final HttpLoggingInterceptor logging;
 
+    /**
+     * Create a new instance with the given tenant's domain, client id and client secret. These values can be obtained at https://manage.auth0.com/#/clients/{YOUR_CLIENT_ID}/settings.
+     *
+     * @param domain       tenant's domain.
+     * @param clientId     the client's id.
+     * @param clientSecret the client's secret.
+     */
     public AuthAPI(String domain, String clientId, String clientSecret) {
         Asserts.assertNotNull(domain, "domain");
         Asserts.assertNotNull(clientId, "client id");
@@ -98,11 +110,11 @@ public AuthorizeUrlBuilder authorizeUrl(String redirectUri) {
     }
 
     /**
-     * Creates a new instance of the {@link AuthorizeUrlBuilder} with the given connection and redirect url parameters.
+     * Creates a new instance of the {@link LogoutUrlBuilder} with the given return-to url.
      *
      * @param returnToUrl the redirect_uri value to set, white-listed in the client settings. Must be already URL Encoded.
      * @param setClientId whether the client_id value must be set or not. This affects the white-list that the Auth0's Dashboard uses to validate the returnTo url.
-     * @return a new instance of the {@link AuthorizeUrlBuilder} to configure.
+     * @return a new instance of the {@link LogoutUrlBuilder} to configure.
      */
     public LogoutUrlBuilder logoutUrl(String returnToUrl, boolean setClientId) {
         Asserts.assertNotNull(returnToUrl, "return to url");
@@ -257,7 +269,7 @@ public AuthRequest login(String emailOrUsername, String password, String realm)
     }
 
     /**
-     * Creates a new request using the 'Client Credentials' grant to get a Token for the given audience.
+     * Creates a new request to get a Token for the given audience using the 'Client Credentials' grant.
      * Default used realm and audience are defined in the "API Authorization Settings" in the account's advanced settings in the Auth0 Dashboard.
      *
      * @param audience the audience of the API to request access to.
@@ -281,7 +293,7 @@ public AuthRequest requestToken(String audience) {
     }
 
     /**
-     * Creates a new request using the 'Authorization Code' grant to exchange the code obtained in the /authorize call.
+     * Creates a new request to exchange the code obtained in the /authorize call using the 'Authorization Code' grant.
      *
      * @param code        the authorization code received from the /authorize call.
      * @param redirectUri the redirect uri sent on the /authorize call.

src/main/java/com/auth0/client/auth/AuthAPI.java

@@ -8,6 +8,9 @@
 import static com.auth0.utils.Asserts.assertNotNull;
 import static com.auth0.utils.Asserts.assertValidUrl;
 
+/**
+ * Class that provides the methods to generate a valid Auth0 Authorize Url. It's based on the https://auth0.com/docs/api/authentication#social docs.
+ */
 public class AuthorizeUrlBuilder {
 
     private final HttpUrl.Builder builder;

src/main/java/com/auth0/client/auth/AuthorizeUrlBuilder.java

@@ -8,6 +8,9 @@
 import static com.auth0.utils.Asserts.assertNotNull;
 import static com.auth0.utils.Asserts.assertValidUrl;
 
+/**
+ * Class that provides the methods to generate a valid Auth0 Logout Url. It's based on the https://auth0.com/docs/api/authentication#logout docs.
+ */
 public class LogoutUrlBuilder {
 
     private final HttpUrl.Builder builder;

src/main/java/com/auth0/client/auth/LogoutUrlBuilder.java

@@ -1,16 +1,20 @@
 package com.auth0.client.mgmt;
 
-import com.auth0.utils.Asserts;
 import com.auth0.json.mgmt.Token;
 import com.auth0.net.CustomRequest;
 import com.auth0.net.Request;
 import com.auth0.net.VoidRequest;
+import com.auth0.utils.Asserts;
 import com.fasterxml.jackson.core.type.TypeReference;
 import okhttp3.HttpUrl;
 import okhttp3.OkHttpClient;
 
 import java.util.List;
 
+/**
+ * Class that provides an implementation of the Blacklists methods of the Management API as defined in https://auth0.com/docs/api/management/v2#!/Blacklists
+ */
+@SuppressWarnings("WeakerAccess")
 public class BlacklistsEntity extends BaseManagementEntity {
 
     BlacklistsEntity(OkHttpClient client, String baseUrl, String apiToken) {
@@ -19,6 +23,7 @@ public class BlacklistsEntity extends BaseManagementEntity {
 
     /**
      * Request all the Blacklisted Tokens with a given audience. A token with scope blacklist:tokens is needed.
+     * See https://auth0.com/docs/api/management/v2#!/Blacklists/get_tokens.
      *
      * @param audience the token audience (aud).
      * @return a Request to execute.
@@ -43,6 +48,7 @@ public Request<List<Token>> getBlacklist(String audience) {
 
     /**
      * Add a Token to the Blacklist. A token with scope blacklist:tokens is needed.
+     * See https://auth0.com/docs/api/management/v2#!/Blacklists/post_tokens.
      *
      * @param token the token to blacklist.
      * @return a Request to execute.

src/main/java/com/auth0/client/mgmt/BlacklistsEntity.java

@@ -1,16 +1,20 @@
 package com.auth0.client.mgmt;
 
-import com.auth0.utils.Asserts;
 import com.auth0.json.mgmt.ClientGrant;
 import com.auth0.net.CustomRequest;
 import com.auth0.net.Request;
 import com.auth0.net.VoidRequest;
+import com.auth0.utils.Asserts;
 import com.fasterxml.jackson.core.type.TypeReference;
 import okhttp3.HttpUrl;
 import okhttp3.OkHttpClient;
 
 import java.util.List;
 
+/**
+ * Class that provides an implementation of the Client Grants methods of the Management API as defined in https://auth0.com/docs/api/management/v2#!/Client_Grants
+ */
+@SuppressWarnings("WeakerAccess")
 public class ClientGrantsEntity extends BaseManagementEntity {
 
     ClientGrantsEntity(OkHttpClient client, String baseUrl, String apiToken) {
@@ -19,6 +23,7 @@ public class ClientGrantsEntity extends BaseManagementEntity {
 
     /**
      * Request all the Client Grants. A token with scope read:client_grants is needed.
+     * See https://auth0.com/docs/api/management/v2#!/Client_Grants/get_client_grants
      *
      * @return a Request to execute.
      */
@@ -38,6 +43,7 @@ public Request<List<ClientGrant>> list() {
 
     /**
      * Create a new Client Grant. A token with scope create:client_grants is needed.
+     * See https://auth0.com/docs/api/management/v2#!/Client_Grants/post_client_grants
      *
      * @param clientId the client id to associate this grant with.
      * @param audience the audience of the grant.
@@ -68,6 +74,7 @@ public Request<ClientGrant> create(String clientId, String audience, String[] sc
 
     /**
      * Delete an existing Client Grant. A token with scope delete:client_grants is needed.
+     * See https://auth0.com/docs/api/management/v2#!/Client_Grants/delete_client_grants_by_id
      *
      * @param clientGrantId the client grant id.
      * @return a Request to execute.
@@ -90,6 +97,7 @@ public Request delete(String clientGrantId) {
 
     /**
      * Update an existing Client Grant. A token with scope update:client_grants is needed.
+     * See https://auth0.com/docs/api/management/v2#!/Client_Grants/patch_client_grants_by_id
      *
      * @param clientGrantId the client grant id.
      * @param scope         the scope to grant.

src/main/java/com/auth0/client/mgmt/ClientGrantsEntity.java

@@ -1,17 +1,21 @@
 package com.auth0.client.mgmt;
 
-import com.auth0.utils.Asserts;
 import com.auth0.json.mgmt.client.Client;
 import com.auth0.net.CustomRequest;
 import com.auth0.net.EmptyBodyRequest;
 import com.auth0.net.Request;
 import com.auth0.net.VoidRequest;
+import com.auth0.utils.Asserts;
 import com.fasterxml.jackson.core.type.TypeReference;
 import okhttp3.HttpUrl;
 import okhttp3.OkHttpClient;
 
 import java.util.List;
 
+/**
+ * Class that provides an implementation of the Clients methods of the Management API as defined in https://auth0.com/docs/api/management/v2#!/Clients
+ */
+@SuppressWarnings("WeakerAccess")
 public class ClientsEntity extends BaseManagementEntity {
 
     ClientsEntity(OkHttpClient client, String baseUrl, String apiToken) {
@@ -20,6 +24,7 @@ public class ClientsEntity extends BaseManagementEntity {
 
     /**
      * Request all the ClientsEntity. A token with scope read:clients is needed. If you also need the client_secret and encryption_key attributes the token must have read:client_keys scope.
+     * See https://auth0.com/docs/api/management/v2#!/Clients/get_clients
      *
      * @return a Request to execute.
      */
@@ -39,6 +44,7 @@ public Request<List<Client>> list() {
 
     /**
      * Request a Client. A token with scope read:clients is needed. If you also need the client_secret and encryption_key attributes the token must have read:client_keys scope.
+     * See https://auth0.com/docs/api/management/v2#!/Clients/get_clients_by_id
      *
      * @param clientId the client id.
      * @return a Request to execute.
@@ -62,6 +68,7 @@ public Request<Client> get(String clientId) {
 
     /**
      * Create a new Client. A token with scope create:clients is needed.
+     * See https://auth0.com/docs/api/management/v2#!/Clients/post_clients
      *
      * @param client the client data to set.
      * @return a Request to execute.
@@ -85,6 +92,7 @@ public Request<Client> create(Client client) {
 
     /**
      * Delete an existing Client. A token with scope delete:clients is needed.
+     * See https://auth0.com/docs/api/management/v2#!/Clients/delete_clients_by_id
      *
      * @param clientId the client id.
      * @return a Request to execute.
@@ -107,6 +115,7 @@ public Request delete(String clientId) {
 
     /**
      * Update an existing Client. A token with scope update:clients is needed. If you also need to update the client_secret and encryption_key attributes the token must have update:client_keys scope.
+     * See https://auth0.com/docs/api/management/v2#!/Clients/patch_clients_by_id
      *
      * @param clientId the client id.
      * @param client   the client data to set.
@@ -133,6 +142,7 @@ public Request<Client> update(String clientId, Client client) {
 
     /**
      * Rotates a Client secret. A token with scope update:client_keys is needed. Note that the generated secret is NOT base64 encoded.
+     * See https://auth0.com/docs/api/management/v2#!/Clients/post_rotate_secret
      *
      * @param clientId the client id.
      * @return a Request to execute.

src/main/java/com/auth0/client/mgmt/ClientsEntity.java

@@ -1,18 +1,22 @@
 package com.auth0.client.mgmt;
 
-import com.auth0.utils.Asserts;
 import com.auth0.client.mgmt.filter.ConnectionFilter;
 import com.auth0.json.mgmt.Connection;
 import com.auth0.net.CustomRequest;
 import com.auth0.net.Request;
 import com.auth0.net.VoidRequest;
+import com.auth0.utils.Asserts;
 import com.fasterxml.jackson.core.type.TypeReference;
 import okhttp3.HttpUrl;
 import okhttp3.OkHttpClient;
 
 import java.util.List;
 import java.util.Map;
 
+/**
+ * Class that provides an implementation of the Clients methods of the Management API as defined in https://auth0.com/docs/api/management/v2#!/Connections
+ */
+@SuppressWarnings("WeakerAccess")
 public class ConnectionsEntity extends BaseManagementEntity {
 
     ConnectionsEntity(OkHttpClient client, String baseUrl, String apiToken) {
@@ -21,6 +25,7 @@ public class ConnectionsEntity extends BaseManagementEntity {
 
     /**
      * Request all the ConnectionsEntity. A token with scope read:connections is needed.
+     * See https://auth0.com/docs/api/management/v2#!/Connections/get_connections
      *
      * @param filter the filter to use. Can be null.
      * @return a Request to execute.
@@ -45,6 +50,7 @@ public Request<List<Connection>> list(ConnectionFilter filter) {
 
     /**
      * Request a Connection. A token with scope read:connections is needed.
+     * See https://auth0.com/docs/api/management/v2#!/Connections/get_connections_by_id
      *
      * @param connectionId the id of the connection to retrieve.
      * @param filter       the filter to use. Can be null.
@@ -73,6 +79,7 @@ public Request<Connection> get(String connectionId, ConnectionFilter filter) {
 
     /**
      * Create a new Connection. A token with scope create:connections is needed.
+     * See https://auth0.com/docs/api/management/v2#!/Connections/post_connections
      *
      * @param connection the connection data to set.
      * @return a Request to execute.
@@ -96,6 +103,7 @@ public Request<Connection> create(Connection connection) {
 
     /**
      * Delete an existing Connection. A token with scope delete:connections is needed.
+     * See https://auth0.com/docs/api/management/v2#!/Connections/delete_connections_by_id
      *
      * @param connectionId the connection id.
      * @return a Request to execute.
@@ -118,6 +126,7 @@ public Request delete(String connectionId) {
 
     /**
      * Update an existing Connection. A token with scope update:connections is needed. Note that if the 'options' value is present it will override all the 'options' values that currently exist.
+     * See https://auth0.com/docs/api/management/v2#!/Connections/patch_connections_by_id
      *
      * @param connectionId the connection id.
      * @param connection   the connection data to set. It can't include name or strategy.
@@ -144,6 +153,7 @@ public Request<Connection> update(String connectionId, Connection connection) {
 
     /**
      * Delete an existing User from the given Database Connection. A token with scope delete:users is needed.
+     * See https://auth0.com/docs/api/management/v2#!/Connections/delete_users_by_email
      *
      * @param connectionId the connection id where the user is stored.
      * @param email        the email of the user to delete.