Add JavaDocs

Do using IntelliJ JavaDocs plugin. Better to have something than nothing.

src/main/java/org/kohsuke/github/GHPullRequest.java

@@ -39,7 +39,7 @@ import static org.kohsuke.github.Previews.SHADOW_CAT;
  * A pull request.
  *
  * @author Kohsuke Kawaguchi
- * @see GHRepository#getPullRequest(int)
+ * @see GHRepository#getPullRequest(int) GHRepository#getPullRequest(int)
  */
 @SuppressWarnings({ "UnusedDeclaration" })
 public class GHPullRequest extends GHIssue implements Refreshable {
@@ -103,6 +103,8 @@ public class GHPullRequest extends GHIssue implements Refreshable {
 
     /**
      * The URL of the patch file. like https://github.com/jenkinsci/jenkins/pull/100.patch
+     *
+     * @return the patch url
      */
     public URL getPatchUrl() {
         return GitHub.parseURL(patch_url);
@@ -110,6 +112,8 @@ public class GHPullRequest extends GHIssue implements Refreshable {
 
     /**
      * The URL of the patch file. like https://github.com/jenkinsci/jenkins/pull/100.patch
+     *
+     * @return the issue url
      */
     public URL getIssueUrl() {
         return GitHub.parseURL(issue_url);
@@ -117,6 +121,8 @@ public class GHPullRequest extends GHIssue implements Refreshable {
 
     /**
      * This points to where the change should be pulled into, but I'm not really sure what exactly it means.
+     *
+     * @return the base
      */
     public GHCommitPointer getBase() {
         return base;
@@ -124,11 +130,20 @@ public class GHPullRequest extends GHIssue implements Refreshable {
 
     /**
      * The change that should be pulled. The tip of the commits to merge.
+     *
+     * @return the head
      */
     public GHCommitPointer getHead() {
         return head;
     }
 
+    /**
+     * Gets issue updated at.
+     *
+     * @return the issue updated at
+     * @throws IOException
+     *             the io exception
+     */
     @Deprecated
     public Date getIssueUpdatedAt() throws IOException {
         return super.getUpdatedAt();
@@ -136,11 +151,18 @@ public class GHPullRequest extends GHIssue implements Refreshable {
 
     /**
      * The diff file, like https://github.com/jenkinsci/jenkins/pull/100.diff
+     *
+     * @return the diff url
      */
     public URL getDiffUrl() {
         return GitHub.parseURL(diff_url);
     }
 
+    /**
+     * Gets merged at.
+     *
+     * @return the merged at
+     */
     public Date getMergedAt() {
         return GitHub.parseDate(merged_at);
     }
@@ -165,36 +187,85 @@ public class GHPullRequest extends GHIssue implements Refreshable {
     // details that are only available via get with ID
     //
 
+    /**
+     * Gets merged by.
+     *
+     * @return the merged by
+     * @throws IOException
+     *             the io exception
+     */
     public GHUser getMergedBy() throws IOException {
         populate();
         return merged_by;
     }
 
+    /**
+     * Gets review comments.
+     *
+     * @return the review comments
+     * @throws IOException
+     *             the io exception
+     */
     public int getReviewComments() throws IOException {
         populate();
         return review_comments;
     }
 
+    /**
+     * Gets additions.
+     *
+     * @return the additions
+     * @throws IOException
+     *             the io exception
+     */
     public int getAdditions() throws IOException {
         populate();
         return additions;
     }
 
+    /**
+     * Gets commits.
+     *
+     * @return the commits
+     * @throws IOException
+     *             the io exception
+     */
     public int getCommits() throws IOException {
         populate();
         return commits;
     }
 
+    /**
+     * Is merged boolean.
+     *
+     * @return the boolean
+     * @throws IOException
+     *             the io exception
+     */
     public boolean isMerged() throws IOException {
         populate();
         return merged;
     }
 
+    /**
+     * Can maintainer modify boolean.
+     *
+     * @return the boolean
+     * @throws IOException
+     *             the io exception
+     */
     public boolean canMaintainerModify() throws IOException {
         populate();
         return maintainer_can_modify;
     }
 
+    /**
+     * Is draft boolean.
+     *
+     * @return the boolean
+     * @throws IOException
+     *             the io exception
+     */
     public boolean isDraft() throws IOException {
         populate();
         return draft;
@@ -206,6 +277,8 @@ public class GHPullRequest extends GHIssue implements Refreshable {
      * @return null if the state has not been determined yet, for example when a PR is newly created. If this method is
      *         called on an instance whose mergeable state is not yet known, API call is made to retrieve the latest
      *         state.
+     * @throws IOException
+     *             the io exception
      */
     public Boolean getMergeable() throws IOException {
         refresh(mergeable);
@@ -220,16 +293,37 @@ public class GHPullRequest extends GHIssue implements Refreshable {
         return mergeable;
     }
 
+    /**
+     * Gets deletions.
+     *
+     * @return the deletions
+     * @throws IOException
+     *             the io exception
+     */
     public int getDeletions() throws IOException {
         populate();
         return deletions;
     }
 
+    /**
+     * Gets mergeable state.
+     *
+     * @return the mergeable state
+     * @throws IOException
+     *             the io exception
+     */
     public String getMergeableState() throws IOException {
         populate();
         return mergeable_state;
     }
 
+    /**
+     * Gets changed files.
+     *
+     * @return the changed files
+     * @throws IOException
+     *             the io exception
+     */
     public int getChangedFiles() throws IOException {
         populate();
         return changed_files;
@@ -237,17 +331,35 @@ public class GHPullRequest extends GHIssue implements Refreshable {
 
     /**
      * See <a href="https://developer.github.com/changes/2013-04-25-deprecating-merge-commit-sha">GitHub blog post</a>
+     *
+     * @return the merge commit sha
+     * @throws IOException
+     *             the io exception
      */
     public String getMergeCommitSha() throws IOException {
         populate();
         return merge_commit_sha;
     }
 
+    /**
+     * Gets requested reviewers.
+     *
+     * @return the requested reviewers
+     * @throws IOException
+     *             the io exception
+     */
     public List<GHUser> getRequestedReviewers() throws IOException {
         refresh(requested_reviewers);
         return Collections.unmodifiableList(Arrays.asList(requested_reviewers));
     }
 
+    /**
+     * Gets requested teams.
+     *
+     * @return the requested teams
+     * @throws IOException
+     *             the io exception
+     */
     public List<GHTeam> getRequestedTeams() throws IOException {
         refresh(requested_teams);
         return Collections.unmodifiableList(Arrays.asList(requested_teams));
@@ -276,6 +388,8 @@ public class GHPullRequest extends GHIssue implements Refreshable {
 
     /**
      * Retrieves all the files associated to this pull request.
+     *
+     * @return the paged iterable
      */
     public PagedIterable<GHPullRequestFileDetail> listFiles() {
         return root.retrieve().asPagedIterable(String.format("%s/files", getApiRoute()),
@@ -284,6 +398,8 @@ public class GHPullRequest extends GHIssue implements Refreshable {
 
     /**
      * Retrieves all the reviews associated to this pull request.
+     *
+     * @return the paged iterable
      */
     public PagedIterable<GHPullRequestReview> listReviews() {
         return root.retrieve().asPagedIterable(String.format("%s/reviews", getApiRoute()), GHPullRequestReview[].class,
@@ -292,6 +408,10 @@ public class GHPullRequest extends GHIssue implements Refreshable {
 
     /**
      * Obtains all the review comments associated with this pull request.
+     *
+     * @return the paged iterable
+     * @throws IOException
+     *             the io exception
      */
     public PagedIterable<GHPullRequestReviewComment> listReviewComments() throws IOException {
         return root.retrieve().asPagedIterable(getApiRoute() + COMMENTS_ACTION, GHPullRequestReviewComment[].class,
@@ -300,6 +420,8 @@ public class GHPullRequest extends GHIssue implements Refreshable {
 
     /**
      * Retrieves all the commits associated to this pull request.
+     *
+     * @return the paged iterable
      */
     public PagedIterable<GHPullRequestCommitDetail> listCommits() {
         return root.retrieve().asPagedIterable(String.format("%s/commits", getApiRoute()),
@@ -307,6 +429,17 @@ public class GHPullRequest extends GHIssue implements Refreshable {
     }
 
     /**
+     * Create review gh pull request review.
+     *
+     * @param body
+     *            the body
+     * @param event
+     *            the event
+     * @param comments
+     *            the comments
+     * @return the gh pull request review
+     * @throws IOException
+     *             the io exception
      * @deprecated Use {@link #createReview()}
      */
     public GHPullRequestReview createReview(String body, @CheckForNull GHPullRequestReviewState event,
@@ -315,6 +448,17 @@ public class GHPullRequest extends GHIssue implements Refreshable {
     }
 
     /**
+     * Create review gh pull request review.
+     *
+     * @param body
+     *            the body
+     * @param event
+     *            the event
+     * @param comments
+     *            the comments
+     * @return the gh pull request review
+     * @throws IOException
+     *             the io exception
      * @deprecated Use {@link #createReview()}
      */
     public GHPullRequestReview createReview(String body, @CheckForNull GHPullRequestReviewState event,
@@ -326,10 +470,30 @@ public class GHPullRequest extends GHIssue implements Refreshable {
         return b.create();
     }
 
+    /**
+     * Create review gh pull request review builder.
+     *
+     * @return the gh pull request review builder
+     */
     public GHPullRequestReviewBuilder createReview() {
         return new GHPullRequestReviewBuilder(this);
     }
 
+    /**
+     * Create review comment gh pull request review comment.
+     *
+     * @param body
+     *            the body
+     * @param sha
+     *            the sha
+     * @param path
+     *            the path
+     * @param position
+     *            the position
+     * @return the gh pull request review comment
+     * @throws IOException
+     *             the io exception
+     */
     public GHPullRequestReviewComment createReviewComment(String body, String sha, String path, int position)
             throws IOException {
         return new Requester(root).method("POST").with("body", body).with("commit_id", sha).with("path", path)
@@ -337,10 +501,26 @@ public class GHPullRequest extends GHIssue implements Refreshable {
                 .wrapUp(this);
     }
 
+    /**
+     * Request reviewers.
+     *
+     * @param reviewers
+     *            the reviewers
+     * @throws IOException
+     *             the io exception
+     */
     public void requestReviewers(List<GHUser> reviewers) throws IOException {
         new Requester(root).method("POST").withLogins("reviewers", reviewers).to(getApiRoute() + REQUEST_REVIEWERS);
     }
 
+    /**
+     * Request team reviewers.
+     *
+     * @param teams
+     *            the teams
+     * @throws IOException
+     *             the io exception
+     */
     public void requestTeamReviewers(List<GHTeam> teams) throws IOException {
         List<String> teamReviewers = new ArrayList<String>(teams.size());
         for (GHTeam team : teams) {
@@ -351,11 +531,13 @@ public class GHPullRequest extends GHIssue implements Refreshable {
 
     /**
      * Merge this pull request.
-     *
+     * <p>
      * The equivalent of the big green "Merge pull request" button.
      *
      * @param msg
      *            Commit message. If null, the default one will be used.
+     * @throws IOException
+     *             the io exception
      */
     public void merge(String msg) throws IOException {
         merge(msg, null);
@@ -363,13 +545,15 @@ public class GHPullRequest extends GHIssue implements Refreshable {
 
     /**
      * Merge this pull request.
-     *
+     * <p>
      * The equivalent of the big green "Merge pull request" button.
      *
      * @param msg
      *            Commit message. If null, the default one will be used.
      * @param sha
      *            SHA that pull request head must match to allow merge.
+     * @throws IOException
+     *             the io exception
      */
     public void merge(String msg, String sha) throws IOException {
         merge(msg, sha, null);
@@ -377,19 +561,26 @@ public class GHPullRequest extends GHIssue implements Refreshable {
 
     /**
      * Merge this pull request, using the specified merge method.
-     *
+     * <p>
      * The equivalent of the big green "Merge pull request" button.
      *
      * @param msg
      *            Commit message. If null, the default one will be used.
+     * @param sha
+     *            the sha
      * @param method
      *            SHA that pull request head must match to allow merge.
+     * @throws IOException
+     *             the io exception
      */
     public void merge(String msg, String sha, MergeMethod method) throws IOException {
         new Requester(root).method("PUT").with("commit_message", msg).with("sha", sha).with("merge_method", method)
                 .to(getApiRoute() + "/merge");
     }
 
+    /**
+     * The enum MergeMethod.
+     */
     public enum MergeMethod {
         MERGE, SQUASH, REBASE
     }