feat: Add Javadoc comments (box/box-codegen#839)

.codegen.json

@@ -1 +1 @@
-{ "engineHash": "0540f75", "specHash": "1ed059a", "version": "10.0.0" }
+{ "engineHash": "47a3d7f", "specHash": "1ed059a", "version": "10.0.0" }

src/main/java/com/box/sdkgen/box/ccgauth/BoxCCGAuth.java

@@ -17,12 +17,22 @@
 
 public class BoxCCGAuth implements Authentication {
 
+  /** Configuration object of Client Credentials Grant auth. */
   public final CCGConfig config;
 
+  /**
+   * An object responsible for storing token. If no custom implementation provided, the token will
+   * be stored in memory.
+   */
   public final TokenStorage tokenStorage;
 
+  /**
+   * The ID of the user or enterprise to authenticate as. If not provided, defaults to the
+   * enterprise ID if set, otherwise defaults to the user ID.
+   */
   public String subjectId;
 
+  /** The type of the subject ID provided. Must be either 'user' or 'enterprise'. */
   public EnumWrapper<PostOAuth2TokenBoxSubjectTypeField> subjectType;
 
   public BoxCCGAuth(CCGConfig config) {
@@ -39,10 +49,16 @@ public BoxCCGAuth(CCGConfig config) {
                 : PostOAuth2TokenBoxSubjectTypeField.ENTERPRISE));
   }
 
+  /** Get a new access token using CCG auth */
   public AccessToken refreshToken() {
     return refreshToken(null);
   }
 
+  /**
+   * Get a new access token using CCG auth
+   *
+   * @param networkSession An object to keep network session state
+   */
   @Override
   public AccessToken refreshToken(NetworkSession networkSession) {
     AuthorizationManager authManager =
@@ -61,10 +77,16 @@ public AccessToken refreshToken(NetworkSession networkSession) {
     return token;
   }
 
+  /** Return a current token or get a new one when not available. */
   public AccessToken retrieveToken() {
     return retrieveToken(null);
   }
 
+  /**
+   * Return a current token or get a new one when not available.
+   *
+   * @param networkSession An object to keep network session state
+   */
   @Override
   public AccessToken retrieveToken(NetworkSession networkSession) {
     AccessToken oldToken = this.tokenStorage.get();
@@ -85,10 +107,30 @@ public String retrieveAuthorizationHeader(NetworkSession networkSession) {
     return String.join("", "Bearer ", token.getAccessToken());
   }
 
+  /**
+   * Create a new BoxCCGAuth instance that uses the provided user ID as the subject ID. May be one
+   * of this application's created App User. Depending on the configured User Access Level, may also
+   * be any other App User or Managed User in the enterprise.
+   * &lt;https://developer.box.com/en/guides/applications/&gt;
+   * &lt;https://developer.box.com/en/guides/authentication/select/&gt;
+   *
+   * @param userId The id of the user to authenticate
+   */
   public BoxCCGAuth withUserSubject(String userId) {
     return withUserSubject(userId, new InMemoryTokenStorage());
   }
 
+  /**
+   * Create a new BoxCCGAuth instance that uses the provided user ID as the subject ID. May be one
+   * of this application's created App User. Depending on the configured User Access Level, may also
+   * be any other App User or Managed User in the enterprise.
+   * &lt;https://developer.box.com/en/guides/applications/&gt;
+   * &lt;https://developer.box.com/en/guides/authentication/select/&gt;
+   *
+   * @param userId The id of the user to authenticate
+   * @param tokenStorage Object responsible for storing token in newly created BoxCCGAuth. If no
+   *     custom implementation provided, the token will be stored in memory.
+   */
   public BoxCCGAuth withUserSubject(String userId, TokenStorage tokenStorage) {
     CCGConfig newConfig =
         new CCGConfig.Builder(this.config.getClientId(), this.config.getClientSecret())
@@ -99,10 +141,22 @@ public BoxCCGAuth withUserSubject(String userId, TokenStorage tokenStorage) {
     return new BoxCCGAuth(newConfig);
   }
 
+  /**
+   * Create a new BoxCCGAuth instance that uses the provided enterprise ID as the subject ID.
+   *
+   * @param enterpriseId The id of the enterprise to authenticate
+   */
   public BoxCCGAuth withEnterpriseSubject(String enterpriseId) {
     return withEnterpriseSubject(enterpriseId, new InMemoryTokenStorage());
   }
 
+  /**
+   * Create a new BoxCCGAuth instance that uses the provided enterprise ID as the subject ID.
+   *
+   * @param enterpriseId The id of the enterprise to authenticate
+   * @param tokenStorage Object responsible for storing token in newly created BoxCCGAuth. If no
+   *     custom implementation provided, the token will be stored in memory.
+   */
   public BoxCCGAuth withEnterpriseSubject(String enterpriseId, TokenStorage tokenStorage) {
     CCGConfig newConfig =
         new CCGConfig.Builder(this.config.getClientId(), this.config.getClientSecret())
@@ -113,6 +167,18 @@ public BoxCCGAuth withEnterpriseSubject(String enterpriseId, TokenStorage tokenS
     return new BoxCCGAuth(newConfig);
   }
 
+  /**
+   * Downscope access token to the provided scopes. Returning a new access token with the provided
+   * scopes, with the original access token unchanged.
+   *
+   * @param scopes The scope(s) to apply to the resulting token.
+   * @param resource The file or folder to get a downscoped token for. If None and shared_link None,
+   *     the resulting token will not be scoped down to just a single item. The resource should be a
+   *     full URL to an item, e.g. https://api.box.com/2.0/files/123456.
+   * @param sharedLink The shared link to get a downscoped token for. If None and item None, the
+   *     resulting token will not be scoped down to just a single item.
+   * @param networkSession An object to keep network session state
+   */
   @Override
   public AccessToken downscopeToken(
       List<String> scopes, String resource, String sharedLink, NetworkSession networkSession) {
@@ -140,10 +206,16 @@ public AccessToken downscopeToken(
     return downscopedToken;
   }
 
+  /** Revoke the current access token and remove it from token storage. */
   public void revokeToken() {
     revokeToken(null);
   }
 
+  /**
+   * Revoke the current access token and remove it from token storage.
+   *
+   * @param networkSession An object to keep network session state
+   */
   @Override
   public void revokeToken(NetworkSession networkSession) {
     AccessToken oldToken = this.tokenStorage.get();

src/main/java/com/box/sdkgen/box/ccgauth/CCGConfig.java

@@ -5,14 +5,25 @@
 
 public class CCGConfig {
 
+  /** Box API key used for identifying the application the user is authenticating with */
   public final String clientId;
 
+  /** Box API secret used for making auth requests. */
   public final String clientSecret;
 
+  /** The ID of the Box Developer Edition enterprise. */
   public String enterpriseId;
 
+  /**
+   * The user id to authenticate. This value is not required. But if it is provided, then the user
+   * will be auto-authenticated at the time of the first API call.
+   */
   public String userId;
 
+  /**
+   * Object responsible for storing token. If no custom implementation provided,the token will be
+   * stored in memory.
+   */
   public TokenStorage tokenStorage;
 
   public CCGConfig(String clientId, String clientSecret) {

src/main/java/com/box/sdkgen/box/developertokenauth/BoxDeveloperTokenAuth.java

@@ -17,8 +17,13 @@ public class BoxDeveloperTokenAuth implements Authentication {
 
   public final String token;
 
+  /** Configuration object of DeveloperTokenAuth. */
   public DeveloperTokenConfig config;
 
+  /**
+   * An object responsible for storing token. If no custom implementation provided, the token will
+   * be stored in memory.
+   */
   public final TokenStorage tokenStorage;
 
   public BoxDeveloperTokenAuth(String token) {
@@ -39,10 +44,16 @@ protected BoxDeveloperTokenAuth(Builder builder) {
             .build();
   }
 
+  /** Retrieves stored developer token */
   public AccessToken retrieveToken() {
     return retrieveToken(null);
   }
 
+  /**
+   * Retrieves stored developer token
+   *
+   * @param networkSession An object to keep network session state
+   */
   @Override
   public AccessToken retrieveToken(NetworkSession networkSession) {
     AccessToken token = this.tokenStorage.get();
@@ -52,10 +63,16 @@ public AccessToken retrieveToken(NetworkSession networkSession) {
     return token;
   }
 
+  /** Developer token cannot be refreshed */
   public AccessToken refreshToken() {
     return refreshToken(null);
   }
 
+  /**
+   * Developer token cannot be refreshed
+   *
+   * @param networkSession An object to keep network session state
+   */
   @Override
   public AccessToken refreshToken(NetworkSession networkSession) {
     throw new BoxSDKError("Developer token has expired. Please provide a new one.");
@@ -71,10 +88,20 @@ public String retrieveAuthorizationHeader(NetworkSession networkSession) {
     return String.join("", "Bearer ", token.getAccessToken());
   }
 
+  /**
+   * Revoke an active Access Token, effectively logging a user out that has been previously
+   * authenticated.
+   */
   public void revokeToken() {
     revokeToken(null);
   }
 
+  /**
+   * Revoke an active Access Token, effectively logging a user out that has been previously
+   * authenticated.
+   *
+   * @param networkSession An object to keep network session state
+   */
   @Override
   public void revokeToken(NetworkSession networkSession) {
     AccessToken token = this.tokenStorage.get();
@@ -94,6 +121,18 @@ public void revokeToken(NetworkSession networkSession) {
     this.tokenStorage.clear();
   }
 
+  /**
+   * Downscope access token to the provided scopes. Returning a new access token with the provided
+   * scopes, with the original access token unchanged.
+   *
+   * @param scopes The scope(s) to apply to the resulting token.
+   * @param resource The file or folder to get a downscoped token for. If None and shared_link None,
+   *     the resulting token will not be scoped down to just a single item. The resource should be a
+   *     full URL to an item, e.g. https://api.box.com/2.0/files/123456.
+   * @param sharedLink The shared link to get a downscoped token for. If None and item None, the
+   *     resulting token will not be scoped down to just a single item.
+   * @param networkSession An object to keep network session state
+   */
   @Override
   public AccessToken downscopeToken(
       List<String> scopes, String resource, String sharedLink, NetworkSession networkSession) {