Merge pull request #181 from AzureAD/sagonzal/updateJavaDoc

Update JavaDoc comments

Author: sangonzal

src/main/java/com/microsoft/aad/msal4j/AuthenticationErrorCode.java

@@ -9,19 +9,21 @@
 public class AuthenticationErrorCode {
 
     /**
-     * In the context of device code user has not yet authenticated via browser
+     * In the context of device code user has not yet authenticated via browser. For more details,
+     * see https://aka.ms/msal4j-device-code
      */
     public final static String AUTHORIZATION_PENDING = "authorization_pending";
 
     /**
      * In the context of device code, this error happens when the device code has expired before
-     * the user signed-in on another device (this is usually after 15 min)
+     * the user signed-in on another device (this is usually after 15 min). For more details, see
+     * https://aka.ms/msal4j-device-code
      */
     public final static String CODE_EXPIRED = "code_expired";
 
     /**
      * Standard Oauth2 protocol error code. It indicates that the application needs to expose
-     * the UI to the user so that user does an interactive action in order to get a new token
+     * the UI to the user so that user does an interactive action in order to get a new token.
      */
     public final static String INVALID_GRANT = "invalid_grant";
 
@@ -32,7 +34,7 @@ public class AuthenticationErrorCode {
 
     /**
      * Password is required for managed user. Will typically happen when trying to do integrated windows authentication
-     * for managed users
+     * for managed users. For more information, see https://aka.ms/msal4j-iwa
      */
     public final static String PASSWORD_REQUIRED_FOR_MANAGED_USER = "password_required_for_managed_user";
 
@@ -60,7 +62,7 @@ public class AuthenticationErrorCode {
     /**
      * The current redirect URI is not a loopback URL. To use the OS browser, a loopback URL must be
      * configured both during app registration as well as when initializing the InteractiveRequestParameters
-     * object
+     * object. For more details, see https://aka.ms/msal4j-interactive-request
      */
     public final static String LOOPBACK_REDIRECT_URI = "loopback_redirect_uri";
 
@@ -70,19 +72,22 @@ public class AuthenticationErrorCode {
     public final static String UNABLE_TO_START_HTTP_LISTENER = "unable_to_start_http_listener";
 
     /**
-     * Authorization result response is invalid, either because format is invalid or it does not contain
-     * an authorization code.
+     * Authorization result response is invalid. Authorization result must contain authorization
+     * code and state.
      */
     public final static String INVALID_AUTHORIZATION_RESULT = "invalid_authorization_result";
 
     /**
      * Redirect URI provided to MSAL is of invalid format. Redirect URL must be a loopback URL.
+     * For more details, see https://aka.ms/msal4j-interactive-request
      */
     public final static String INVALID_REDIRECT_URI = "invalid_redirect_uri";
 
     /**
      * MSAL was unable to open the user-default browser. This is either because the current platform
-     * does not support {@link java.awt.Desktop} or {@link java.awt.Desktop.Action#BROWSE}
+     * does not support {@link java.awt.Desktop} or {@link java.awt.Desktop.Action#BROWSE}. Interactive
+     * requests require that the client have a system default browser. For more details, see
+     * https://aka.ms/msal4j-interactive-request
      */
     public final static String DESKTOP_BROWSER_NOT_SUPPORTED = "desktop_browser_not_supported";
 }

src/main/java/com/microsoft/aad/msal4j/AuthorizationCodeParameters.java

@@ -22,16 +22,27 @@
 @AllArgsConstructor(access = AccessLevel.PRIVATE)
 public class AuthorizationCodeParameters {
 
+    /**
+     * Authorization code acquired in the first step of OAuth2.0 authorization code flow. For more
+     * details, see https://aka.ms/msal4j-authorization-code-flow
+     */
     @NonNull
     private String authorizationCode;
 
+    /**
+     * Redirect URI registered in the Azure portal, and which was used in the first step of OAuth2.0
+     * authorization code flow. For more details, see https://aka.ms/msal4j-authorization-code-flow
+     */
     @NonNull
     private URI redirectUri;
 
+    /**
+     * Scopes to which the application is requesting access
+     */
     private Set<String> scopes;
 
     /**
-     * Code verifier used for PKCE.
+     * Code verifier used for PKCE. For more details, see https://tools.ietf.org/html/rfc7636
      */
     private String codeVerifier;
 

src/main/java/com/microsoft/aad/msal4j/ClientApplicationBase.java

@@ -22,7 +22,8 @@
 import static com.microsoft.aad.msal4j.ParameterValidationUtils.validateNotNull;
 
 /**
- * Abstract class containing common API methods and properties.
+ * Abstract class containing common methods and properties to both {@link PublicClientApplication}
+ * and {@link ConfidentialClientApplication}.
  */
 abstract class ClientApplicationBase implements IClientApplicationBase {
 

src/main/java/com/microsoft/aad/msal4j/ClientCredentialFactory.java

@@ -10,7 +10,8 @@
 import java.security.cert.X509Certificate;
 
 /**
- * Factory for creating client credentials used in confidential client flows
+ * Factory for creating client credentials used in confidential client flows. For more details, see
+ * https://aka.ms/msal4j-client-credentials
  */
 public class ClientCredentialFactory {
 

src/main/java/com/microsoft/aad/msal4j/ClientCredentialParameters.java

@@ -20,6 +20,9 @@
 @AllArgsConstructor(access = AccessLevel.PRIVATE)
 public class ClientCredentialParameters {
 
+    /**
+     * Scopes for which the application is requesting access to.
+     */
     @NonNull
     private Set<String> scopes;
 

src/main/java/com/microsoft/aad/msal4j/ConfidentialClientApplication.java

@@ -22,6 +22,9 @@
 /**
  * Class to be used to acquire tokens for confidential client applications (Web Apps, Web APIs,
  * and daemon applications).
+ * For details see {@link IConfidentialClientApplication}
+ *
+ * Conditionally thread-safe
  */
 public class ConfidentialClientApplication extends ClientApplicationBase implements IConfidentialClientApplication {
 

src/main/java/com/microsoft/aad/msal4j/DeviceCodeFlowParameters.java

@@ -13,17 +13,28 @@
 
 /**
  * Object containing parameters for device code flow. Can be used as parameter to
- * {@link PublicClientApplication#acquireToken(DeviceCodeFlowParameters)}
+ * {@link PublicClientApplication#acquireToken(DeviceCodeFlowParameters)}. For more details,
+ * see https://aka.ms/msal4j-device-code
  */
 @Builder
 @Accessors(fluent = true)
 @Getter
 @AllArgsConstructor(access = AccessLevel.PRIVATE)
 public class DeviceCodeFlowParameters {
 
+    /**
+     * Scopes to which the application is requesting access to.
+     */
     @NonNull
     private Set<String> scopes;
 
+    /**
+     * Receives the device code returned from the first step of Oauth2.0 device code flow. The
+     * {@link DeviceCode#verificationUri} and the {@link DeviceCode#userCode} should be shown
+     * to the end user.
+     *
+     * For more details, see https://aka.ms/msal4j-device-code
+     */
     @NonNull
     private Consumer<DeviceCode> deviceCodeConsumer;
 

src/main/java/com/microsoft/aad/msal4j/HttpMethod.java

@@ -4,7 +4,7 @@
 package com.microsoft.aad.msal4j;
 
 /**
- * Http request method
+ * Http request method.
  */
 public enum HttpMethod {
 

src/main/java/com/microsoft/aad/msal4j/IAccount.java

@@ -8,6 +8,7 @@
 /**
  * Interface representing a single user account. An IAccount is returned in the {@link IAuthenticationResult}
  * property, and is used as parameter in {@link SilentParameters#builder(Set, IAccount)} )}
+ *
  */
 public interface IAccount {
 

src/main/java/com/microsoft/aad/msal4j/IClientAssertion.java

@@ -6,6 +6,8 @@
 /**
  * Credential type containing an assertion of type
  * "urn:ietf:params:oauth:token-type:jwt".
+ *
+ * For more details, see https://aka.ms/msal4j-client-credentials
  */
 public interface IClientAssertion extends IClientCredential{