Add javadocs for BoxFolder

Author: gcurtis

src/main/java/com/box/sdk/BoxFolder.java

@@ -10,6 +10,10 @@
 import com.eclipsesource.json.JsonObject;
 import com.eclipsesource.json.JsonValue;
 
+/**
+ * Represents a folder on Box. This class can be used to iterate through a folder's contents, collaborate a folder with
+ * another user or group, and perform other common folder operations (move, copy, delete, etc.).
+ */
 public final class BoxFolder extends BoxItem implements Iterable<BoxItem> {
     private static final String UPLOAD_FILE_URL_BASE = "https://upload.box.com/api/2.0/";
     private static final URLTemplate CREATE_FOLDER_URL = new URLTemplate("folders");
@@ -22,16 +26,32 @@ public final class BoxFolder extends BoxItem implements Iterable<BoxItem> {
 
     private final URL folderURL;
 
+    /**
+     * Constructs a BoxFolder for a folder with a given ID.
+     * @param  api the API connection to be used by the folder.
+     * @param  id  the ID of the folder.
+     */
     public BoxFolder(BoxAPIConnection api, String id) {
         super(api, id);
 
         this.folderURL = FOLDER_INFO_URL_TEMPLATE.build(this.getAPI().getBaseURL(), this.getID());
     }
 
+    /**
+     * Gets the current user's root folder.
+     * @param  api the API connection to be used by the folder.
+     * @return     the user's root folder.
+     */
     public static BoxFolder getRootFolder(BoxAPIConnection api) {
         return new BoxFolder(api, "0");
     }
 
+    /**
+     * Adds a collaborator to this folder.
+     * @param  collaborator the collaborator to add.
+     * @param  role         the role of the collaborator.
+     * @return              info about the new collaboration.
+     */
     public BoxCollaboration.Info collaborate(BoxCollaborator collaborator, BoxCollaboration.Role role) {
         JsonObject accessibleByField = new JsonObject();
         accessibleByField.add("id", collaborator.getID());
@@ -45,6 +65,13 @@ public BoxCollaboration.Info collaborate(BoxCollaborator collaborator, BoxCollab
         return this.collaborate(accessibleByField, role);
     }
 
+    /**
+     * Adds a collaborator to this folder. An email will be sent to the collaborator if they don't already have a Box
+     * account.
+     * @param  email the email address of the collaborator to add.
+     * @param  role  the role of the collaborator.
+     * @return       info about the new collaboration.
+     */
     public BoxCollaboration.Info collaborate(String email, BoxCollaboration.Role role) {
         JsonObject accessibleByField = new JsonObject();
         accessibleByField.add("login", email);
@@ -76,6 +103,10 @@ private BoxCollaboration.Info collaborate(JsonObject accessibleByField, BoxColla
         return info;
     }
 
+    /**
+     * Gets information about all of the collaborations for this folder.
+     * @return a collection of information about the collaborations for this folder.
+     */
     public Collection<BoxCollaboration.Info> getCollaborations() {
         BoxAPIConnection api = this.getAPI();
         URL url = GET_COLLABORATIONS_URL.build(api.getBaseURL(), this.getID());
@@ -114,6 +145,10 @@ public BoxFolder.Info getInfo(String... fields) {
         return new Info(response.getJSON());
     }
 
+    /**
+     * Updates the information about this folder with any info fields that have been modified locally.
+     * @param info the updated info.
+     */
     public void updateInfo(BoxFolder.Info info) {
         BoxJSONRequest request = new BoxJSONRequest(this.getAPI(), this.folderURL, "PUT");
         request.setBody(info.getPendingChanges());
@@ -148,6 +183,11 @@ public BoxFolder.Info copy(BoxFolder destination, String newName) {
         return copiedFolder.new Info(responseJSON);
     }
 
+    /**
+     * Creates a new child folder inside this folder.
+     * @param  name the new folder's name.
+     * @return      the created folder.
+     */
     public BoxFolder createFolder(String name) {
         JsonObject parent = new JsonObject();
         parent.add("id", this.getID());
@@ -165,22 +205,26 @@ public BoxFolder createFolder(String name) {
         return new BoxFolder(this.getAPI(), createdFolder.get("id").asString());
     }
 
+    /**
+     * Deletes this folder, optionally recursively deleting all of its contents.
+     * @param recursive true to recursively delete this folder's contents; otherwise false.
+     */
     public void delete(boolean recursive) {
         URL url = DELETE_FOLDER_URL.build(this.getAPI().getBaseURL(), this.getID(), recursive);
         BoxAPIRequest request = new BoxAPIRequest(this.getAPI(), url, "DELETE");
         BoxAPIResponse response = request.send();
         response.disconnect();
     }
 
+    /**
+     * Moves this folder to another folder.
+     * @param destination the destination folder.
+     */
     public void move(BoxFolder destination) {
-        this.move(destination.getID());
-    }
-
-    public void move(String destinationID) {
         BoxJSONRequest request = new BoxJSONRequest(this.getAPI(), this.folderURL, "PUT");
 
         JsonObject parent = new JsonObject();
-        parent.add("id", destinationID);
+        parent.add("id", destination.getID());
 
         JsonObject updateInfo = new JsonObject();
         updateInfo.add("parent", parent);
@@ -190,6 +234,10 @@ public void move(String destinationID) {
         response.disconnect();
     }
 
+    /**
+     * Renames this folder.
+     * @param newName the new name of the folder.
+     */
     public void rename(String newName) {
         BoxJSONRequest request = new BoxJSONRequest(this.getAPI(), this.folderURL, "PUT");
 
@@ -201,13 +249,27 @@ public void rename(String newName) {
         response.disconnect();
     }
 
+    /**
+     * Uploads a new file to this folder.
+     * @param  fileContent a stream containing the contents of the file to upload.
+     * @param  name        the name to give the uploaded file.
+     * @return             the uploaded file.
+     */
     public BoxFile uploadFile(InputStream fileContent, String name) {
         FileUploadParams uploadInfo = new FileUploadParams()
             .setContent(fileContent)
             .setName(name);
         return this.uploadFile(uploadInfo);
     }
 
+    /**
+     * Uploads a new file to this folder while reporting the progress to a ProgressListener.
+     * @param  fileContent a stream containing the contents of the file to upload.
+     * @param  name        the name to give the uploaded file.
+     * @param  fileSize    the size of the file used for determining the progress of the upload.
+     * @param  listener    a listener for monitoring the upload's progress.
+     * @return             the uploaded file.
+     */
     public BoxFile uploadFile(InputStream fileContent, String name, long fileSize, ProgressListener listener) {
         FileUploadParams uploadInfo = new FileUploadParams()
             .setContent(fileContent)
@@ -217,6 +279,11 @@ public BoxFile uploadFile(InputStream fileContent, String name, long fileSize, P
         return this.uploadFile(uploadInfo);
     }
 
+    /**
+     * Uploads a new file to this folder with custom upload settings.
+     * @param  uploadInfo the custom upload settings.
+     * @return            the uploaded file.
+     */
     public BoxFile uploadFile(FileUploadParams uploadInfo) {
         URL uploadURL = UPLOAD_FILE_URL.build(UPLOAD_FILE_URL_BASE);
         BoxMultipartRequest request = new BoxMultipartRequest(getAPI(), uploadURL);
@@ -249,19 +316,37 @@ public BoxFile uploadFile(FileUploadParams uploadInfo) {
         return new BoxFile(getAPI(), uploadedFileID);
     }
 
+    /**
+     * Returns an iterator over the items in this folder.
+     * @return an iterator over the items in this folder.
+     */
     public Iterator<BoxItem> iterator() {
         return new BoxItemIterator(BoxFolder.this.getAPI(), BoxFolder.this.getID());
     }
 
+    /**
+     * Contains additional information about a BoxFolder.
+     */
     public class Info extends BoxItem.Info {
+        /**
+         * Constructs an empty Info object.
+         */
         public Info() {
             super();
         }
 
+        /**
+         * Constructs an Info object by parsing information from a JSON string.
+         * @param  json the JSON string to parse.
+         */
         public Info(String json) {
             super(json);
         }
 
+        /**
+         * Constructs an Info object using an already parsed JSON object.
+         * @param  jsonObject the parsed JSON object.
+         */
         protected Info(JsonObject jsonObject) {
             super(jsonObject);
         }