Add/improve javadocs for interface classes

Author: Avery-Dunn

msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/IAcquireTokenParameters.java

@@ -7,16 +7,61 @@
 import java.util.Set;
 
 /**
- * Parameters shared by all acquireToken methods
+ * Interface representing common parameters shared across all token acquisition methods in MSAL.
+ * <p>
+ * This interface defines the core parameters that are common to all token acquisition operations,
+ * regardless of the specific authentication flow being used (interactive, silent, username/password, etc.).
+ * Various parameter classes in the library implement this interface to provide a consistent way to
+ * configure token requests.
  */
 interface IAcquireTokenParameters {
+
+    /**
+     * Gets the set of scopes (permissions) requested for the access token.
+     * <p>
+     * Scopes represent the permissions that the application is requesting access to.
+     *
+     * @return A set of scope strings being requested for the access token.
+     */
     Set<String> scopes();
 
+    /**
+     * Gets the claims request parameter that will be sent with the authentication request.
+     * <p>
+     * The claims request parameter can be used to request specific claims to be returned in the token,
+     * to request MFA authentication, or to control other aspects of token issuance.
+     *
+     * @return A {@link ClaimsRequest} object containing the requested claims, or null if no claims are specified.
+     */
     ClaimsRequest claims();
 
+    /**
+     * Gets additional HTTP headers to be included in the token request.
+     * <p>
+     * These headers will be added to the HTTP requests sent to the token endpoint.
+     * This can be useful for scenarios requiring custom headers for proxies or for diagnostic purposes.
+     *
+     * @return A map of additional HTTP headers to include with the token request, or null if no extra headers are needed.
+     */
     Map<String, String> extraHttpHeaders();
 
+    /**
+     * Gets the tenant identifier for the token request.
+     * <p>
+     * When specified, this value overrides the tenant specified in the application's authority URL.
+     * It can be a tenant ID (GUID), domain name, or one of the special values like "common" or "organizations".
+     *
+     * @return The tenant identifier to use for the token request, or null to use the tenant from the authority URL.
+     */
     String tenant();
 
+    /**
+     * Gets additional query parameters to be included in the token request.
+     * <p>
+     * These parameters will be added to the query string in requests to the authorization and token endpoints.
+     * This can be useful for scenarios requiring custom parameters that aren't explicitly supported in the library.
+     *
+     * @return A map of additional query parameters to include with the token request, or null if no extra parameters are needed.
+     */
     Map<String, String> extraQueryParameters();
 }

msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/IApplicationBase.java

@@ -9,38 +9,48 @@
 import java.util.concurrent.CompletableFuture;
 
 /**
- * Interface representing an application for which tokens can be acquired.
+ * Base interface representing a client application that can acquire tokens from the Microsoft identity platform.
+ * Defines common functionality across different application types (public client, confidential client,
+ * and managed identity applications).
  */
 interface IApplicationBase {
 
     String DEFAULT_AUTHORITY = "https://login.microsoftonline.com/common/";
 
     /**
-     * @return a boolean value which determines whether Pii (personally identifiable information) will be logged in
+     * Gets whether personally identifiable information (PII) is included in log messages.
+     *
+     * @return A boolean value which determines whether PII (personally identifiable information) will be included in log messages.
+     * When true, PII will be logged; when false, PII will be masked or omitted from logs.
      */
     boolean logPii();
 
     /**
-     * @return Correlation ID which is used for diagnostics purposes, is attached to token service requests
-     * Default value is random UUID
+     * Gets the correlation ID used for tracing requests through the authentication system.
+     *
+     * @return Correlation ID which is used for diagnostics purposes and is attached to token service requests.
+     * The default value is a random UUID.
      */
     String correlationId();
 
     /**
-     * Sets HTTP client to be used by the client application for all HTTP requests. Allows for fine-grained
-     * configuration of HTTP client.
-
-     * @return instance of IHttpClient used by the application
+     * Gets the HTTP client used by the application for all HTTP requests.
+     *
+     * @return Instance of IHttpClient used by the application for network communication with the Microsoft identity platform.
      */
     IHttpClient httpClient();
 
     /**
-     * @return proxy used by the application for all network communication.
+     * Gets the proxy configuration used by the application for network communication.
+     *
+     * @return Proxy used by the application for all network communication. Returns null if no proxy is configured.
      */
     Proxy proxy();
 
     /**
-     * @return SSLSocketFactory used by the application for all network communication.
+     * Gets the SSL socket factory used by the application for secure network communication.
+     *
+     * @return SSLSocketFactory used by the application for all secure network communication. Returns null if no custom SSL socket factory is configured.
      */
     SSLSocketFactory sslSocketFactory();
 }

msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/IBroker.java

@@ -9,44 +9,84 @@
 import java.util.concurrent.CompletableFuture;
 
 /**
- * Used to define the basic set of methods that all Brokers must implement
+ * Interface defining the core functionality required for authentication brokers.
+ * <p>
+ * Authentication brokers provide a centralized way to handle authentication across multiple applications
+ * on a device or platform. They can offer benefits such as single sign-on (SSO) between applications,
+ * consistent authentication experiences, and leveraging platform security features.
  * <p>
  * All methods are marked as default so they can be referenced by MSAL Java without an implementation,
- * and most will simply throw an exception if not overridden by an IBroker implementation
+ * and most will simply throw an exception if not overridden by an IBroker implementation.
  */
 public interface IBroker {
 
     /**
-     * Acquire a token silently, i.e. without direct user interaction
+     * Acquires a token silently without user interaction.
      * <p>
      * This may be accomplished by returning tokens from a token cache, using cached refresh tokens to get new tokens,
-     * or via any authentication flow where a user is not prompted to enter credentials
+     * or via any authentication flow where a user is not prompted to enter credentials.
+     *
+     * @param application The public client application requesting the token
+     * @param requestParameters Parameters for the silent token request
+     * @return A CompletableFuture containing the authentication result with tokens and account information
+     * @throws MsalClientException If no broker implementation is available
      */
     default CompletableFuture<IAuthenticationResult> acquireToken(PublicClientApplication application, SilentParameters requestParameters) {
         throw new MsalClientException("Broker implementation missing", AuthenticationErrorCode.MISSING_BROKER);
     }
 
     /**
-     * Acquire a token interactively, by prompting users to enter their credentials in some way
+     * Acquires a token interactively by prompting the user to enter credentials.
+     * <p>
+     * This method presents a user interface requesting credentials from the user and handles the
+     * interactive authentication flow.
+     *
+     * @param application The public client application requesting the token
+     * @param parameters Parameters for the interactive token request
+     * @return A CompletableFuture containing the authentication result with tokens and account information
+     * @throws MsalClientException If no broker implementation is available
      */
     default CompletableFuture<IAuthenticationResult> acquireToken(PublicClientApplication application, InteractiveRequestParameters parameters) {
         throw new MsalClientException("Broker implementation missing", AuthenticationErrorCode.MISSING_BROKER);
     }
 
     /**
-     * Acquire a token silently, i.e. without direct user interaction, using username/password authentication
+     * Acquires a token silently using username and password authentication.
+     * <p>
+     * This method enables resource owner password credentials (ROPC) flow through a broker.
+     * Note that this flow is not recommended for production applications as it requires handling
+     * user credentials directly.
+     *
+     * @param application The public client application requesting the token
+     * @param parameters Parameters containing username, password and other request details
+     * @return A CompletableFuture containing the authentication result with tokens and account information
+     * @throws MsalClientException If no broker implementation is available
      */
     default CompletableFuture<IAuthenticationResult> acquireToken(PublicClientApplication application, UserNamePasswordParameters parameters) {
         throw new MsalClientException("Broker implementation missing", AuthenticationErrorCode.MISSING_BROKER);
     }
 
+    /**
+     * Removes an account from the broker's token cache.
+     * <p>
+     * This method allows applications to sign out users and remove their tokens from the broker cache.
+     *
+     * @param application The public client application requesting the account removal
+     * @param account The account to be removed from the token cache
+     * @throws MsalClientException If no broker implementation is available
+     */
     default void removeAccount(PublicClientApplication application, IAccount account) throws MsalClientException {
         throw new MsalClientException("Broker implementation missing", AuthenticationErrorCode.MISSING_BROKER);
     }
 
     /**
-     * Returns whether a broker is available and ready to use on this machine, allowing the use of the methods
-     * in this interface and other broker-only features in MSAL Java
+     * Checks whether a broker is available and ready to use on this machine.
+     * <p>
+     * Applications should call this method before attempting to use broker-specific features
+     * to determine if a broker is installed and accessible.
+     *
+     * @return true if a broker is available for authentication, false otherwise
+     * @throws MsalClientException If no broker implementation is available
      */
     default boolean isBrokerAvailable() {
         throw new MsalClientException("Broker implementation missing", AuthenticationErrorCode.MISSING_BROKER);

msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/IClientApplicationBase.java

@@ -11,51 +11,65 @@
 import java.util.concurrent.CompletableFuture;
 
 /**
- * Interface representing an application for which tokens can be acquired.
+ * Interface representing a client application that can acquire tokens from the Microsoft identity platform.
+ * This interface serves as the base for both public client applications (desktop/mobile apps) and
+ * confidential client applications (web apps/APIs), defining common functionality for token acquisition.
+ * <p>
+ * Client applications are registered in the Microsoft identity platform and have their own identity,
+ * represented by an application ID (client ID).
  */
 interface IClientApplicationBase extends IApplicationBase {
 
     /**
+     * Gets the client ID (application ID) for this application.
+     *
      * @return Client ID (Application ID) of the application as registered in the application registration portal
      * (portal.azure.com) and as passed in the constructor of the application
      */
     String clientId();
 
     /**
+     * Gets the authority URL for this application.
+     *
      * @return URL of the authority, or security token service (STS) from which MSAL will acquire security tokens.
      * Default value is {@link IClientApplicationBase#DEFAULT_AUTHORITY}
      */
     String authority();
 
     /**
-     * @return a boolean value which determines whether the authority needs to be verified against a list of known authorities.
+     * Gets whether the authority URL should be validated against a list of known authorities.
+     *
+     * @return A boolean value which determines whether the authority needs to be verified against a list of known authorities.
+     * When true, MSAL will validate the authority against a list of well-known authorities. Set to false only for
+     * development/testing with custom authority URLs.
      */
     boolean validateAuthority();
 
-//    /**
-//     * @return Telemetry consumer that will receive telemetry events emitted by the library.
-//     */
-//     java.util.function.Consumer<java.util.List<java.util.HashMap<String, String>>> telemetryConsumer();
-
     /**
      * Computes the URL of the authorization request letting the user sign-in and consent to the
      * application. The URL target the /authorize endpoint of the authority configured in the
      * application object.
      * <p>
      * Once the user successfully authenticates, the response should contain an authorization code,
-     * which can then be passed in to{@link AbstractClientApplicationBase#acquireToken(AuthorizationCodeParameters)}
-     * to be exchanged for a token
+     * which can then be passed in to {@link AbstractClientApplicationBase#acquireToken(AuthorizationCodeParameters)}
+     * to be exchanged for a token.
      *
-     * @param parameters {@link AuthorizationRequestUrlParameters}
-     * @return url of the authorization endpoint where the user can sign-in and consent to the application.
+     * @param parameters {@link AuthorizationRequestUrlParameters} containing the details needed to create the authorization URL,
+     *                   such as scopes, response type, and redirect URI
+     * @return URL of the authorization endpoint where the user can sign-in and consent to the application
      */
     URL getAuthorizationRequestUrl(AuthorizationRequestUrlParameters parameters);
 
     /**
      * Acquires security token from the authority using an authorization code previously received.
+     * <p>
+     * This is typically used as the second step in an authorization code flow, after the user has
+     * authenticated and provided consent at the authorization endpoint, resulting in an authorization code.
      *
-     * @param parameters {@link AuthorizationCodeParameters}
-     * @return A {@link CompletableFuture} object representing the {@link IAuthenticationResult} of the call.
+     * @param parameters {@link AuthorizationCodeParameters} containing the authorization code and other information
+     *                   required to exchange the code for tokens
+     * @return A {@link CompletableFuture} object representing the {@link IAuthenticationResult} of the call,
+     *         which contains the requested tokens and account information
      */
     CompletableFuture<IAuthenticationResult> acquireToken(AuthorizationCodeParameters parameters);
 

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

@@ -7,11 +7,17 @@
  * Credential type containing an assertion of type
  * "urn:ietf:params:oauth:token-type:jwt".
  * <p>
+ * Client assertions provide a way for confidential client applications to authenticate themselves
+ * to the Microsoft identity platform without sending a client secret. Instead, the application
+ * uses a JWT token as a credential.
+ * <p>
  * For more details, see https://aka.ms/msal4j-client-credentials
  */
 public interface IClientAssertion extends IClientCredential {
 
     /**
+     * Gets the JWT token used for client authentication.
+     *
      * @return Jwt token encoded as a base64 URL encoded string
      */
     String assertion();

msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/IClientCredential.java

@@ -4,7 +4,19 @@
 package com.microsoft.aad.msal4j;
 
 /**
- * Interface representing an application credential
+ * Interface representing an application credential used for client authentication.
+ * <p>
+ * Client credentials are used by confidential client applications to authenticate themselves
+ * to the Microsoft identity platform when requesting tokens. This is used in scenarios where the
+ * application is acting on its own behalf (client credentials flow) or on behalf of a user
+ * (authorization code flow with client authentication).
+ * <p>
+ * MSAL supports several types of client credentials:
+ * <ul>
+ *   <li>Client secrets - A string secret configured for the application in the Azure portal</li>
+ *   <li>Client certificates - An X.509 certificate that can be used to authenticate the application</li>
+ *   <li>Client assertions - A JWT token signed with a private key that proves the client's identity</li>
+ * </ul>
  * <p>
  * For more details, see https://aka.ms/msal4j-client-credentials
  */

msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/IEnvironmentVariables.java

@@ -3,8 +3,24 @@
 
 package com.microsoft.aad.msal4j;
 
+/**
+ * Interface for accessing environment variables within the library.
+ * <p>
+ * This interface abstracts the mechanism for retrieving environment variables,
+ * which allows for better testability and flexibility in different hosting environments.
+ * It's primarily used within the library for accessing configuration settings and
+ * credentials that may be stored in environment variables.
+ */
 interface IEnvironmentVariables {
 
-
+    /**
+     * Retrieves the value of the specified environment variable.
+     * <p>
+     * This method provides access to system environment variables that may contain
+     * configuration settings or credentials needed for authentication.
+     *
+     * @param envVariable The name of the environment variable to retrieve.
+     * @return The string value of the environment variable, or null if the variable is not defined.
+     */
     String getEnvironmentVariable(String envVariable);
 }