fix: fixed javadoc errors (#945)

* fix: fixed javadoc errors

Update javadoc source version to 8 and modified configuration to ignore 'missing' javadoc comments since missing unnecessary @returns are getting flagged as an error.

* Add missing @params and @return

* linting fix

* revert pom.xml changes

* Addressing PR comments

Co-authored-by: Leo <[email protected]>

Author: aeitzman

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

@@ -120,6 +120,9 @@ private Builder() {}
      * Sets the list of {@link AccessBoundaryRule}'s.
      *
      * <p>This list must not exceed 10 rules.
+     *
+     * @param rule the collection of rules to be set, should not be null
+     * @return this {@code Builder} object
      */
     public Builder setRules(List<AccessBoundaryRule> rule) {
       accessBoundaryRules = new ArrayList<>(checkNotNull(rule));
@@ -211,6 +214,9 @@ private Builder() {}
        * access to.
        *
        * <p>For example: "//storage.googleapis.com/projects/_/buckets/example".
+       *
+       * @param availableResource the resource name to set
+       * @return this {@code Builder} object
        */
       public Builder setAvailableResource(String availableResource) {
         this.availableResource = availableResource;
@@ -222,6 +228,9 @@ public Builder setAvailableResource(String availableResource) {
        * roles prefixed by inRole.
        *
        * <p>For example: {"inRole:roles/storage.objectViewer"}.
+       *
+       * @param availablePermissions the collection of permissions to set, should not be null
+       * @return this {@code Builder} object
        */
       public Builder setAvailablePermissions(List<String> availablePermissions) {
         this.availablePermissions = new ArrayList<>(checkNotNull(availablePermissions));
@@ -233,6 +242,9 @@ public Builder setAvailablePermissions(List<String> availablePermissions) {
        * inRole.
        *
        * <p>For example: "inRole:roles/storage.objectViewer".
+       *
+       * @param availablePermission a permission to add, should not be null
+       * @return this {@code Builder} object
        */
       public Builder addAvailablePermission(String availablePermission) {
         if (availablePermissions == null) {
@@ -245,6 +257,9 @@ public Builder addAvailablePermission(String availablePermission) {
       /**
        * Sets the availability condition which is an IAM condition that defines constraints to apply
        * to the token expressed in CEL format.
+       *
+       * @param availabilityCondition the {@code AvailabilityCondition} to set
+       * @return this {@code Builder} object
        */
       public Builder setAvailabilityCondition(AvailabilityCondition availabilityCondition) {
         this.availabilityCondition = availabilityCondition;
@@ -318,19 +333,32 @@ private Builder() {}
          * <p>This expression specifies the Cloud Storage object where permissions are available.
          * See <a href='https://cloud.google.com/iam/docs/conditions-overview#cel'>for more
          * information.</a>
+         *
+         * @param expression the expression to set
+         * @return this {@code Builder} object
          */
         public Builder setExpression(String expression) {
           this.expression = expression;
           return this;
         }
 
-        /** Sets the optional title that identifies the purpose of the condition. */
+        /**
+         * Sets the optional title that identifies the purpose of the condition.
+         *
+         * @param title the title to set
+         * @return this {@code Builder} object
+         */
         public Builder setTitle(String title) {
           this.title = title;
           return this;
         }
 
-        /** Sets the description that details the purpose of the condition. */
+        /**
+         * Sets the description that details the purpose of the condition.
+         *
+         * @param description the description to set
+         * @return this {@code Builder} object
+         */
         public Builder setDescription(String description) {
           this.description = description;
           return this;

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

@@ -159,9 +159,25 @@ protected ExternalAccountCredentials(
   }
 
   /**
-   * See {@link ExternalAccountCredentials#ExternalAccountCredentials(HttpTransportFactory, String,
-   * String, String, CredentialSource, String, String, String, String, String, Collection)}
+   * Constructor with minimum identifying information and custom HTTP transport. Does not support
+   * workforce credentials.
    *
+   * @param transportFactory HTTP transport factory, creates the transport used to get access tokens
+   * @param audience the Security Token Service audience, which is usually the fully specified
+   *     resource name of the workload/workforce pool provider
+   * @param subjectTokenType the Security Token Service subject token type based on the OAuth 2.0
+   *     token exchange spec. Indicates the type of the security token in the credential file
+   * @param tokenUrl the Security Token Service token exchange endpoint
+   * @param tokenInfoUrl the endpoint used to retrieve account related information. Required for
+   *     gCloud session account identification.
+   * @param credentialSource the external credential source
+   * @param serviceAccountImpersonationUrl the URL for the service account impersonation request.
+   *     This URL is required for some APIs. If this URL is not available, the access token from the
+   *     Security Token Service is used directly. May be null.
+   * @param quotaProjectId the project used for quota and billing purposes. May be null.
+   * @param clientId client ID of the service account from the console. May be null.
+   * @param clientSecret client secret of the service account from the console. May be null.
+   * @param scopes the scopes to request during the authorization grant. May be null.
    * @param environmentProvider the environment provider. May be null. Defaults to {@link
    *     SystemEnvironmentProvider}.
    */
@@ -211,6 +227,8 @@ protected ExternalAccountCredentials(
   /**
    * Internal constructor with minimum identifying information and custom HTTP transport. See {@link
    * ExternalAccountCredentials.Builder}.
+   *
+   * @param builder the {@code Builder} object used to construct the credentials.
    */
   protected ExternalAccountCredentials(ExternalAccountCredentials.Builder builder) {
     this.transportFactory =
@@ -494,6 +512,7 @@ protected AccessToken exchangeExternalCredentialForAccessToken(
    * source.
    *
    * @return the external subject token
+   * @throws IOException if the subject token cannot be retrieved
    */
   public abstract String retrieveSubjectToken() throws IOException;
 
@@ -522,7 +541,7 @@ public String getServiceAccountImpersonationUrl() {
     return serviceAccountImpersonationUrl;
   }
 
-  /** The service account email to be impersonated, if available. */
+  /** @return The service account email to be impersonated, if available */
   @Nullable
   public String getServiceAccountEmail() {
     if (serviceAccountImpersonationUrl == null || serviceAccountImpersonationUrl.isEmpty()) {
@@ -567,8 +586,8 @@ EnvironmentProvider getEnvironmentProvider() {
   }
 
   /**
-   * Returns whether the current configuration is for Workforce Pools (which enable 3p user
-   * identities, rather than workloads).
+   * @return whether the current configuration is for Workforce Pools (which enable 3p user
+   *     identities, rather than workloads)
    */
   public boolean isWorkforcePoolConfiguration() {
     Pattern workforceAudiencePattern =
@@ -728,7 +747,12 @@ protected Builder(ExternalAccountCredentials credentials) {
       this.serviceAccountImpersonationOptions = credentials.serviceAccountImpersonationOptions;
     }
 
-    /** Sets the HTTP transport factory, creates the transport used to get access tokens. */
+    /**
+     * Sets the HTTP transport factory, creates the transport used to get access tokens.
+     *
+     * @param transportFactory the {@code HttpTransportFactory} to set
+     * @return this {@code Builder} object
+     */
     public Builder setHttpTransportFactory(HttpTransportFactory transportFactory) {
       this.transportFactory = transportFactory;
       return this;
@@ -737,6 +761,9 @@ public Builder setHttpTransportFactory(HttpTransportFactory transportFactory) {
     /**
      * Sets the Security Token Service audience, which is usually the fully specified resource name
      * of the workload/workforce pool provider.
+     *
+     * @param audience the Security Token Service audience to set
+     * @return this {@code Builder} object
      */
     public Builder setAudience(String audience) {
       this.audience = audience;
@@ -746,19 +773,32 @@ public Builder setAudience(String audience) {
     /**
      * Sets the Security Token Service subject token type based on the OAuth 2.0 token exchange
      * spec. Indicates the type of the security token in the credential file.
+     *
+     * @param subjectTokenType the Security Token Service subject token type to set
+     * @return this {@code Builder} object
      */
     public Builder setSubjectTokenType(String subjectTokenType) {
       this.subjectTokenType = subjectTokenType;
       return this;
     }
 
-    /** Sets the Security Token Service token exchange endpoint. */
+    /**
+     * Sets the Security Token Service token exchange endpoint.
+     *
+     * @param tokenUrl the Security Token Service token exchange url to set
+     * @return this {@code Builder} object
+     */
     public Builder setTokenUrl(String tokenUrl) {
       this.tokenUrl = tokenUrl;
       return this;
     }
 
-    /** Sets the external credential source. */
+    /**
+     * Sets the external credential source.
+     *
+     * @param credentialSource the {@code CredentialSource} to set
+     * @return this {@code Builder} object
+     */
     public Builder setCredentialSource(CredentialSource credentialSource) {
       this.credentialSource = credentialSource;
       return this;
@@ -768,6 +808,9 @@ public Builder setCredentialSource(CredentialSource credentialSource) {
      * Sets the optional URL used for service account impersonation, which is required for some
      * APIs. If this URL is not available, the access token from the Security Token Service is used
      * directly.
+     *
+     * @param serviceAccountImpersonationUrl the service account impersonation url to set
+     * @return this {@code Builder} object
      */
     public Builder setServiceAccountImpersonationUrl(String serviceAccountImpersonationUrl) {
       this.serviceAccountImpersonationUrl = serviceAccountImpersonationUrl;
@@ -777,31 +820,54 @@ public Builder setServiceAccountImpersonationUrl(String serviceAccountImpersonat
     /**
      * Sets the optional endpoint used to retrieve account related information. Required for gCloud
      * session account identification.
+     *
+     * @param tokenInfoUrl the token info url to set
+     * @return this {@code Builder} object
      */
     public Builder setTokenInfoUrl(String tokenInfoUrl) {
       this.tokenInfoUrl = tokenInfoUrl;
       return this;
     }
 
-    /** Sets the optional project used for quota and billing purposes. */
+    /**
+     * Sets the optional project used for quota and billing purposes.
+     *
+     * @param quotaProjectId the quota and billing project id to set
+     * @return this {@code Builder} object
+     */
     public Builder setQuotaProjectId(String quotaProjectId) {
       this.quotaProjectId = quotaProjectId;
       return this;
     }
 
-    /** Sets the optional client ID of the service account from the console. */
+    /**
+     * Sets the optional client ID of the service account from the console.
+     *
+     * @param clientId the service account client id to set
+     * @return this {@code Builder} object
+     */
     public Builder setClientId(String clientId) {
       this.clientId = clientId;
       return this;
     }
 
-    /** Sets the optional client secret of the service account from the console. */
+    /**
+     * Sets the optional client secret of the service account from the console.
+     *
+     * @param clientSecret the service account client secret to set
+     * @return this {@code Builder} object
+     */
     public Builder setClientSecret(String clientSecret) {
       this.clientSecret = clientSecret;
       return this;
     }
 
-    /** Sets the optional scopes to request during the authorization grant. */
+    /**
+     * Sets the optional scopes to request during the authorization grant.
+     *
+     * @param scopes the request scopes to set
+     * @return this {@code Builder} object
+     */
     public Builder setScopes(Collection<String> scopes) {
       this.scopes = scopes;
       return this;
@@ -811,18 +877,32 @@ public Builder setScopes(Collection<String> scopes) {
      * Sets the optional workforce pool user project number when the credential corresponds to a
      * workforce pool and not a workload identity pool. The underlying principal must still have
      * serviceusage.services.use IAM permission to use the project for billing/quota.
+     *
+     * @param workforcePoolUserProject the workforce pool user project number to set
+     * @return this {@code Builder} object
      */
     public Builder setWorkforcePoolUserProject(String workforcePoolUserProject) {
       this.workforcePoolUserProject = workforcePoolUserProject;
       return this;
     }
 
-    /** Sets the optional service account impersonation options. */
+    /**
+     * Sets the optional service account impersonation options.
+     *
+     * @param optionsMap the service account impersonation options to set
+     * @return this {@code Builder} object
+     */
     public Builder setServiceAccountImpersonationOptions(Map<String, Object> optionsMap) {
       this.serviceAccountImpersonationOptions = new ServiceAccountImpersonationOptions(optionsMap);
       return this;
     }
 
+    /**
+     * Sets the optional Environment Provider.
+     *
+     * @param environmentProvider the {@code EnvironmentProvider} to set
+     * @return this {@code Builder} object
+     */
     Builder setEnvironmentProvider(EnvironmentProvider environmentProvider) {
       this.environmentProvider = environmentProvider;
       return this;

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

@@ -84,17 +84,17 @@
  *   "code": "401",
  *   "message": "Error message."
  * }
+ * </pre>
  *
- * <p> The `expiration_time` field in the JSON response is only required for successful
- *  responses when an output file was specified in the credential configuration.
+ * <p>The `expiration_time` field in the JSON response is only required for successful responses
+ * when an output file was specified in the credential configuration.
  *
- * The auth libraries will populate certain environment variables that will be accessible by the
+ * <p>The auth libraries will populate certain environment variables that will be accessible by the
  * executable, such as: GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE, GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE,
  * GOOGLE_EXTERNAL_ACCOUNT_INTERACTIVE, GOOGLE_EXTERNAL_ACCOUNT_IMPERSONATED_EMAIL, and
  * GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE.
  *
  * <p>Please see this repositories README for a complete executable request/response specification.
- * </pre>
  */
 public class PluggableAuthCredentials extends ExternalAccountCredentials {