Complete the javadoc of NoteApi and LabelApi (#105)

Stel000 · gmessner · commit 5e7248d67f1b · 2017-12-04T07:55:21.000-08:00
* Complete the javadoc of NoteApi and LabelApi

* Fix createLabel and updateIssueNote
diff --git a/src/main/java/org/gitlab4j/api/LabelsApi.java b/src/main/java/org/gitlab4j/api/LabelsApi.java
@@ -1,67 +1,158 @@
 package org.gitlab4j.api;
 
-import java.util.List;
+import org.gitlab4j.api.models.Label;
 
 import javax.ws.rs.core.GenericType;
 import javax.ws.rs.core.Response;
-
-import org.gitlab4j.api.models.Label;
+import java.util.List;
 
 public class LabelsApi extends AbstractApi {
 
     public LabelsApi(GitLabApi gitLabApi) {
         super(gitLabApi);
     }
 
+    /**
+     * Get all labels of the specified project. Only returns the first page
+     *
+     * @param projectId the project ID to get the labels for
+     * @return a list of project's labels
+     * @throws GitLabApiException if any exception occurs
+     */
     public List<Label> getLabels(Integer projectId) throws GitLabApiException {
         return (getLabels(projectId, 1, getDefaultPerPage()));
     }
 
+    /**
+     * Get all labels of the specified project to using the specified page and per page setting
+     *
+     * @param projectId the project ID to get the labels for
+     * @param page      the page to get
+     * @param perPage   the number of issues per page
+     * @return a list of project's labels in the specified range
+     * @throws GitLabApiException if any exception occurs
+     */
     public List<Label> getLabels(Integer projectId, int page, int perPage) throws GitLabApiException {
 
         if (projectId == null) {
             throw new RuntimeException("projectId cannot be null");
         }
 
-		Response response = get(javax.ws.rs.core.Response.Status.OK, getPageQueryParams(page, perPage), "projects", projectId, "labels");
+        Response response = get(javax.ws.rs.core.Response.Status.OK, getPageQueryParams(page, perPage), "projects", projectId, "labels");
         return (response.readEntity(new GenericType<List<Label>>() {}));
     }
 
+    /**
+     * Create a label
+     *
+     * @param projectId   the project ID to create a label for
+     * @param name        the name for the label
+     * @param color       the color for the label
+     * @param description the description for the label
+     * @return the created Label instance
+     * @throws GitLabApiException if any exception occurs
+     */
     public Label createLabel(Integer projectId, String name, String color, String description) throws GitLabApiException {
         return (createLabel(projectId, name, color, description, null));
     }
 
+    /**
+     * Create a label
+     *
+     * @param projectId the project ID to create a label for
+     * @param name      the name for the label
+     * @param color     the color for the label
+     * @return the created Label instance
+     * @throws GitLabApiException if any exception occurs
+     */
     public Label createLabel(Integer projectId, String name, String color) throws GitLabApiException {
         return (createLabel(projectId, name, color, null, null));
     }
 
+    /**
+     * Create a label
+     *
+     * @param projectId the project ID to create a label for
+     * @param name      the name for the label
+     * @param color     the color for the label
+     * @param priority  the priority for the label
+     * @return the created Label instance
+     * @throws GitLabApiException if any exception occurs
+     */
     public Label createLabel(Integer projectId, String name, String color, Integer priority) throws GitLabApiException {
         return (createLabel(projectId, name, color, null, priority));
     }
 
+    /**
+     *  Create a label
+     *
+     * @param projectId the project ID to create a label for
+     * @param name the name for the label
+     * @param color the color for the label
+     * @param description the description for the label
+     * @param priority the priority for the label
+     * @return the created Label instance
+     * @throws GitLabApiException if any exception occurs
+     */
     public Label createLabel(Integer projectId, String name, String color, String description, Integer priority) throws GitLabApiException {
 
-	    if (projectId == null) {
+        if (projectId == null) {
             throw new RuntimeException("projectId cannot be null");
         }
 
-	    GitLabApiForm formData = new GitLabApiForm()
+        GitLabApiForm formData = new GitLabApiForm()
                 .withParam("name", name, true)
                 .withParam("color", color, true)
                 .withParam("description", description)
                 .withParam("priority", priority);
-        Response response = post(Response.Status.OK, formData, "projects", projectId, "labels");
+        Response response = post(Response.Status.CREATED, formData, "projects", projectId, "labels");
         return (response.readEntity(Label.class));
     }
 
+
+    /**
+     * Update the specified label
+     *
+     * @param projectId the project ID to update a label for
+     * @param name the name for the label
+     * @param newName the new name for the label
+     * @param description the description for the label
+     * @param priority the priority for the label
+     * @return the modified Label instance
+     * @throws GitLabApiException if any exception occurs
+     */
     public Label updateLabelName(Integer projectId, String name, String newName, String description, Integer priority) throws GitLabApiException {
         return (updateLabel(projectId, name, newName, null, description, priority));
     }
 
+
+    /**
+     * Update the specified label
+     *
+     * @param projectId the project ID to update a label for
+     * @param name the name for the label
+     * @param color the color for the label
+     * @param description the description for the label
+     * @param priority the priority for the label
+     * @return the modified Label instance
+     * @throws GitLabApiException if any exception occurs
+     */
     public Label updateLabelColor(Integer projectId, String name, String color, String description, Integer priority) throws GitLabApiException {
         return (updateLabel(projectId, name, null, color, description, priority));
     }
 
+    /**
+     * Update the specified label
+     *
+     * @param projectId the project ID to update a label for
+     * @param name the name for the label
+     * @param newName the new name for the label
+     * @param color the color for the label
+     * @param description the description for the label
+     * @param priority the priority for the label
+     * @return the modified Label instance
+     * @throws GitLabApiException if any exception occurs
+     */
     public Label updateLabel(Integer projectId, String name, String newName, String color, String description, Integer priority) throws GitLabApiException {
 
         if (projectId == null) {
@@ -78,6 +169,13 @@ public Label updateLabel(Integer projectId, String name, String newName, String
         return (response.readEntity(Label.class));
     }
 
+    /**
+     * Delete the specified label
+     *
+     * @param projectId the project ID to delete a label for
+     * @param name the name for the label
+     * @throws GitLabApiException if any exception occurs
+     */
     public void deleteLabel(Integer projectId, String name) throws GitLabApiException {
 
         if (projectId == null) {
@@ -90,11 +188,28 @@ public void deleteLabel(Integer projectId, String name) throws GitLabApiExceptio
         delete(expectedStatus, formData.asMap(), "projects", projectId, "labels");
     }
 
+    /**
+     * Subscribe a specified label
+     *
+     * @param projectId the project ID to subscribe a label for
+     * @param labelId the lable ID
+     * @return HttpStatusCode 503
+     * @throws GitLabApiException if any exception occurs
+     */
     public Label subscribeLabel(Integer projectId, Integer labelId) throws GitLabApiException {
         Response response = post(Response.Status.NOT_MODIFIED, getDefaultPerPageParam(), "projects", projectId, "labels", labelId, "subscribe");
         return (response.readEntity(Label.class));
     }
 
+
+    /**
+     * Unsubscribe a specified label
+     *
+     * @param projectId the project ID to unsubscribe a label for
+     * @param labelId the lable ID
+     * @return HttpStatusCode 503
+     * @throws GitLabApiException if any exception occurs
+     */
     public Label unsubscribeLabel(Integer projectId, Integer labelId) throws GitLabApiException {
         Response response = post(Response.Status.NOT_MODIFIED, getDefaultPerPageParam(), "projects", projectId, "labels", labelId, "unsubscribe");
         return (response.readEntity(Label.class));
diff --git a/src/main/java/org/gitlab4j/api/NotesApi.java b/src/main/java/org/gitlab4j/api/NotesApi.java
@@ -1,12 +1,11 @@
 package org.gitlab4j.api;
 
-import java.util.Date;
-import java.util.List;
+import org.gitlab4j.api.models.Note;
 
 import javax.ws.rs.core.GenericType;
 import javax.ws.rs.core.Response;
-
-import org.gitlab4j.api.models.Note;
+import java.util.Date;
+import java.util.List;
 
 public class NotesApi extends AbstractApi {
 
@@ -109,15 +108,43 @@ public Pager<Note> getIssueNotes(Integer projectId, Integer issueIid, int itemsP
         return (new Pager<Note>(this, Note.class, itemsPerPage, null, "projects", projectId, "issues", issueIid, "notes"));
     }
 
+    /**
+     * Get the specified issues's note.
+     *
+     * @param projectId the project ID to get the issues for
+     * @param issueIid  the issue IID to get the notes for
+     * @param noteId    the ID of the Note to get
+     * @return a Note instance for the specified IDs
+     * @throws GitLabApiException if any exception occurs
+     */
     public Note getIssueNote(Integer projectId, Integer issueIid, Integer noteId) throws GitLabApiException {
         Response response = get(Response.Status.OK, getDefaultPerPageParam(), "projects", projectId, "issues", issueIid, "notes", noteId);
         return (response.readEntity(Note.class));
     }
 
+    /**
+     * Create a issues's note.
+     *
+     * @param projectId the project ID to create the issues for
+     * @param issueIid  the issue IID to create the notes for
+     * @param body      the content of note
+     * @return the created Note instance
+     * @throws GitLabApiException if any exception occurs
+     */
     public Note createIssueNote(Integer projectId, Integer issueIid, String body) throws GitLabApiException {
         return (createIssueNote(projectId, issueIid, body, null));
     }
 
+    /**
+     * Create a issues's note.
+     *
+     * @param projectId the project ID to create the issues for
+     * @param issueIid  the issue IID to create the notes for
+     * @param body      the content of note
+     * @param createdAt the created time of note
+     * @return the created Note instance
+     * @throws GitLabApiException if any exception occurs
+     */
     public Note createIssueNote(Integer projectId, Integer issueIid, String body, Date createdAt) throws GitLabApiException {
         if (projectId == null) {
             throw new RuntimeException("projectId cannot be null");
@@ -129,16 +156,34 @@ public Note createIssueNote(Integer projectId, Integer issueIid, String body, Da
         return (response.readEntity(Note.class));
     }
 
-    public Note updateIssueNote(Integer projectId, Integer issueIid, String body) throws GitLabApiException {
+    /**
+     * Update the specified issues's note.
+     *
+     * @param projectId the project ID to update the issues for
+     * @param issueIid  the issue IID to update the notes for
+     * @param nodeId    the ID of the node to update
+     * @param body      the update content for the Note
+     * @return the modified Note instance
+     * @throws GitLabApiException if any exception occurs
+     */
+    public Note updateIssueNote(Integer projectId, Integer issueIid, Integer nodeId, String body) throws GitLabApiException {
         if (projectId == null) {
             throw new RuntimeException("projectId cannot be null");
         }
         GitLabApiForm formData = new GitLabApiForm()
                 .withParam("body", body, true);
-        Response response = put(Response.Status.CREATED, formData.asMap(), "projects", projectId, "issues", issueIid, "notes");
+        Response response = put(Response.Status.CREATED, formData.asMap(), "projects", projectId, "issues", issueIid, "notes", nodeId);
         return (response.readEntity(Note.class));
     }
 
+    /**
+     * Delete the specified issues's note.
+     *
+     * @param projectId the project ID to delete the issues for
+     * @param issueIid the issue IID to delete the notes for
+     * @param noteId the ID of the node to delete
+     * @throws GitLabApiException if any exception occurs
+     */
     public void deleteIssueNote(Integer projectId, Integer issueIid, Integer noteId) throws GitLabApiException {
         if (projectId == null) {
             throw new RuntimeException("projectId cannot be null");
