Add javadocs to classes and methods that were made public.

Author: nbayati

cab-token-generator/pom.xml

@@ -16,6 +16,7 @@
     <dependency>
       <groupId>com.google.auth</groupId>
       <artifactId>google-auth-library-oauth2-http</artifactId>
+      <version>${project.version}</version>
     </dependency>
   </dependencies>
 

oauth2_http/java/com/google/auth/oauth2/OAuth2Credentials.java

@@ -484,6 +484,15 @@ protected static <T> T newInstance(String className) throws IOException, ClassNo
     }
   }
 
+  /**
+   * Returns the first service provider from the given service loader.
+   *
+   * @param clazz The class of the service provider to load.
+   * @param defaultInstance The default instance to return if no service providers are found.
+   * @param <T> The type of the service provider.
+   * @return The first service provider from the service loader, or the {@code defaultInstance} if no
+   *     service providers are found.
+   */
   public static <T> T getFromServiceLoader(Class<? extends T> clazz, T defaultInstance) {
     return Iterables.getFirst(ServiceLoader.load(clazz), defaultInstance);
   }

oauth2_http/java/com/google/auth/oauth2/StsRequestHandler.java

@@ -50,7 +50,17 @@
 import java.util.List;
 import javax.annotation.Nullable;
 
-/** Implements the OAuth 2.0 token exchange based on https://tools.ietf.org/html/rfc8693. */
+/**
+ * Implements the OAuth 2.0 token exchange based on
+ * <a href="https://tools.ietf.org/html/rfc8693">RFC 8693</a>.
+ *
+ * <p>This class handles the process of exchanging one type of token for another using the
+ * Security Token Service (STS). It constructs and sends the token exchange request to the STS
+ * endpoint and parses the response to create an {@link StsTokenExchangeResponse} object.
+ *
+ * <p>Use the {@link #newBuilder(String, StsTokenExchangeRequest, HttpRequestFactory)} method to
+ * create a new builder for constructing an instance of this class.
+ */
 public final class StsRequestHandler {
   private static final String TOKEN_EXCHANGE_GRANT_TYPE =
       "urn:ietf:params:oauth:grant-type:token-exchange";
@@ -85,6 +95,14 @@ private StsRequestHandler(
     this.internalOptions = internalOptions;
   }
 
+  /**
+   * Returns a new builder for creating an instance of {@link StsRequestHandler}.
+   *
+   * @param tokenExchangeEndpoint The STS token exchange endpoint.
+   * @param stsTokenExchangeRequest The STS token exchange request.
+   * @param httpRequestFactory The HTTP request factory to use for sending the request.
+   * @return A new builder instance.
+   */
   public static Builder newBuilder(
       String tokenExchangeEndpoint,
       StsTokenExchangeRequest stsTokenExchangeRequest,

oauth2_http/java/com/google/auth/oauth2/StsTokenExchangeRequest.java

@@ -38,8 +38,16 @@
 import javax.annotation.Nullable;
 
 /**
- * Defines an OAuth 2.0 token exchange request. Based on
- * https://tools.ietf.org/html/rfc8693#section-2.1.
+ * Represents an OAuth 2.0 token exchange request, as defined in
+ * <a href="https://tools.ietf.org/html/rfc8693#section-2.1">RFC 8693, Section 2.1</a>.
+ *
+ * <p>This class encapsulates the parameters necessary for making a token exchange request to
+ * Google Security Token Service (STS). It includes the subject token, subject token type, optional
+ * parameters like acting party, scopes, resource, audience, requested token type, and internal
+ * options.
+ *
+ * <p>Instances of this class are immutable. Use the {@link #newBuilder(String, String)} method to
+ * create a new builder.
  */
 public final class StsTokenExchangeRequest {
   private static final String GRANT_TYPE = "urn:ietf:params:oauth:grant-type:token-exchange";
@@ -73,6 +81,15 @@ private StsTokenExchangeRequest(
     this.internalOptions = internalOptions;
   }
 
+  /**
+   * Returns a new {@link StsTokenExchangeRequest.Builder} instance.
+   *
+   * @param subjectToken The token being exchanged. This represents the credentials being used
+   *        to authorize the token exchange request.
+   * @param subjectTokenType The type of the {@code subjectToken}.  For example,
+   *        {@link OAuth2Utils#TOKEN_TYPE_ACCESS_TOKEN}.
+   * @return A new builder for creating {@code StsTokenExchangeRequest} instances.
+   */
   public static Builder newBuilder(String subjectToken, String subjectTokenType) {
     return new Builder(subjectToken, subjectTokenType);
   }

oauth2_http/java/com/google/auth/oauth2/StsTokenExchangeResponse.java

@@ -40,8 +40,14 @@
 import javax.annotation.Nullable;
 
 /**
- * Defines an OAuth 2.0 token exchange successful response. Based on
- * https://tools.ietf.org/html/rfc8693#section-2.2.1.
+ * Represents an OAuth 2.0 token exchange request to the Google Security Token Service (STS), as
+ * defined in <a href="https://tools.ietf.org/html/rfc8693#section-2.1">RFC 8693, Section 2.1</a>.
+ *
+ * <p>This class encapsulates the parameters for the request, including the subject token and its
+ * type, along with optional parameters like acting party, scopes, resource, audience, requested
+ * token type, and internal options.
+ *
+ * <p>Instances are immutable. Use {@link #newBuilder(String, String, String)} to create a builder.
  */
 public final class StsTokenExchangeResponse {
   private final AccessToken accessToken;
@@ -76,6 +82,15 @@ private StsTokenExchangeResponse(
     this.accessBoundarySessionKey = accessBoundarySessionKey;
   }
 
+  /**
+   * Returns a new {@link StsTokenExchangeResponse.Builder} instance.
+   *
+   * @param accessToken The exchanged access token.
+   * @param issuedTokenType The issued token type.  For example,
+   *     {@link OAuth2Utils#TOKEN_TYPE_ACCESS_TOKEN}.
+   * @param tokenType The token type (e.g., "Bearer").
+   * @return A new builder for creating {@link StsTokenExchangeResponse} instances.
+   */
   public static Builder newBuilder(String accessToken, String issuedTokenType, String tokenType) {
     return new Builder(accessToken, issuedTokenType, tokenType);
   }