Merge pull request #2042 from rnveach/javadocs

fixed various javadoc issues

Author: bitwiseman

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

@@ -27,19 +27,19 @@
  * set().otherName(value);
  * </pre>
  * <p>
- * If {@link S} is the same as {@link R}, {@link #with(String, Object)} will commit changes after the first value change
- * and return a {@link R} from {@link #done()}.
+ * If {@code S} is the same as {@code R}, {@link #with(String, Object)} will commit changes after the first value change
+ * and return a {@code R} from {@link #done()}.
  * </p>
  * <p>
- * If {@link S} is not the same as {@link R}, {@link #with(String, Object)} will batch together multiple changes and let
+ * If {@code S} is not the same as {@code R}, {@link #with(String, Object)} will batch together multiple changes and let
  * the user call {@link #done()} when they are ready.
  *
  * @author Liam Newman
  * @param <R>
  *            Final return type built by this builder returned when {@link #done()}} is called.
  * @param <S>
- *            Intermediate return type for this builder returned by calls to {@link #with(String, Object)}. If {@link S}
- *            the same as {@link R}, this builder will commit changes after each call to {@link #with(String, Object)}.
+ *            Intermediate return type for this builder returned by calls to {@link #with(String, Object)}. If {@code S}
+ *            the same as {@code R}, this builder will commit changes after each call to {@link #with(String, Object)}.
  */
 abstract class AbstractBuilder<R, S> extends GitHubInteractiveObject implements GitHubRequestBuilderDone<R> {
 
@@ -68,7 +68,7 @@ abstract class AbstractBuilder<R, S> extends GitHubInteractiveObject implements
      * @param finalReturnType
      *            the final return type for built by this builder returned when {@link #done()}} is called.
      * @param intermediateReturnType
-     *            the intermediate return type of type {@link S} returned by calls to {@link #with(String, Object)}.
+     *            the intermediate return type of type {@code S} returned by calls to {@link #with(String, Object)}.
      *            Must either be equal to {@code builtReturnType} or this instance must be castable to this class. If
      *            not, the constructor will throw {@link IllegalArgumentException}.
      * @param root
@@ -113,10 +113,10 @@ public R done() throws IOException {
     /**
      * Applies a value to a name for this builder.
      *
-     * If {@link S} is the same as {@link R}, this method will commit changes after the first value change and return a
-     * {@link R} from {@link #done()}.
+     * If {@code S} is the same as {@code R}, this method will commit changes after the first value change and return a
+     * {@code R} from {@link #done()}.
      *
-     * If {@link S} is not the same as {@link R}, this method will return an {@link S} and letting the caller batch
+     * If {@code S} is not the same as {@code R}, this method will return an {@code S} and letting the caller batch
      * together multiple changes and call {@link #done()} when they are ready.
      *
      * @param name
@@ -137,10 +137,10 @@ protected S with(@Nonnull String name, Object value) throws IOException {
     /**
      * Chooses whether to return a continuing builder or an updated data record
      *
-     * If {@link S} is the same as {@link R}, this method will commit changes after the first value change and return a
-     * {@link R} from {@link #done()}.
+     * If {@code S} is the same as {@code R}, this method will commit changes after the first value change and return a
+     * {@code R} from {@link #done()}.
      *
-     * If {@link S} is not the same as {@link R}, this method will return an {@link S} and letting the caller batch
+     * If {@code S} is not the same as {@code R}, this method will return an {@code S} and letting the caller batch
      * together multiple changes and call {@link #done()} when they are ready.
      *
      * @return either a continuing builder or an updated data record

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

@@ -10,7 +10,7 @@
  * Base class for creating or updating a discussion.
  *
  * @param <S>
- *            Intermediate return type for this builder returned by calls to {@link #with(String, Object)}. If {@link S}
+ *            Intermediate return type for this builder returned by calls to {@link #with(String, Object)}. If {@code S}
  *            the same as {@link GHLabel}, this builder will commit changes after each call to
  *            {@link #with(String, Object)}.
  */
@@ -23,7 +23,7 @@ class GHDiscussionBuilder<S> extends AbstractBuilder<GHDiscussion, S> {
      *
      * @param intermediateReturnType
      *            Intermediate return type for this builder returned by calls to {@link #with(String, Object)}. If
-     *            {@link S} the same as {@link GHDiscussion}, this builder will commit changes after each call to
+     *            {@code S} the same as {@link GHDiscussion}, this builder will commit changes after each call to
      *            {@link #with(String, Object)}.
      * @param team
      *            the GitHub team. Updates will be sent to the root of this team.

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

@@ -10,7 +10,7 @@
  * The Class GHLabelBuilder.
  *
  * @param <S>
- *            Intermediate return type for this builder returned by calls to {@link #with(String, Object)}. If {@link S}
+ *            Intermediate return type for this builder returned by calls to {@link #with(String, Object)}. If {@code S}
  *            the same as {@link GHLabel}, this builder will commit changes after each call to
  *            {@link #with(String, Object)}.
  */
@@ -21,7 +21,7 @@ class GHLabelBuilder<S> extends AbstractBuilder<GHLabel, S> {
      *
      * @param intermediateReturnType
      *            Intermediate return type for this builder returned by calls to {@link #with(String, Object)}. If
-     *            {@link S} the same as {@link GHLabel}, this builder will commit changes after each call to
+     *            {@code S} the same as {@link GHLabel}, this builder will commit changes after each call to
      *            {@link #with(String, Object)}.
      * @param root
      *            the GitHub instance to which updates will be sent

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

@@ -326,8 +326,8 @@ public static class UnknownLimitRecord extends Record {
          * The number of seconds until a {@link UnknownLimitRecord} will expire.
          *
          * This is set to a somewhat short duration, rather than a long one. This avoids
-         * {@link {@link GitHubClient#rateLimit(RateLimitTarget)}} requesting rate limit updates continuously, but also
-         * avoids holding on to stale unknown records indefinitely.
+         * {@link GitHubClient#rateLimit(RateLimitTarget)} requesting rate limit updates continuously, but also avoids
+         * holding on to stale unknown records indefinitely.
          *
          * When merging {@link GHRateLimit} instances, {@link UnknownLimitRecord}s will be superseded by incoming
          * regular {@link Record}s.

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

@@ -17,7 +17,7 @@ public class GHRepositoryVariableBuilder<S> extends AbstractBuilder<GHRepository
      *
      * @param intermediateReturnType
      *            Intermediate return type for this builder returned by calls to {@link #with(String, Object)}. If
-     *            {@link S} the same as {@link GHRepositoryVariable}, this builder will commit changes after each call
+     *            {@code S} the same as {@link GHRepositoryVariable}, this builder will commit changes after each call
      *            to {@link #with(String, Object)}.
      * @param root
      *            the GitHub instance to which updates will be sent

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

@@ -257,8 +257,8 @@ public PagedIterable<GHGist> listGists() {
      * @return The LDAP information
      * @throws IOException
      *             the io exception
-     * @see <a
-     *      href=https://docs.github.com/en/enterprise-server@3.3/admin/identity-and-access-management/authenticating-users-for-your-github-enterprise-server-instance/using-ldap>Github
+     * @see <a href=
+     *      "https://docs.github.com/en/enterprise-server@3.3/admin/identity-and-access-management/authenticating-users-for-your-github-enterprise-server-instance/using-ldap">Github
      *      LDAP</a>
      */
     public Optional<String> getLdapDn() throws IOException {

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

@@ -684,8 +684,8 @@ public Map<String, GHOrganization> getMyOrganizations() throws IOException {
      * OAuth Apps must authenticate using an OAuth token.
      *
      * @return the paged iterable of GHMarketplaceUserPurchase
-     * @see <a href="https://developer.github.com/v3/apps/marketplace/#get-a-users-marketplace-purchases">Get a user's
-     *      Marketplace purchases</a>
+     * @see <a href="https://developer.github.com/v3/apps/marketplace/#get-a-users-marketplace-purchases">Get a
+     *      user&apos;s Marketplace purchases</a>
      */
     public PagedIterable<GHMarketplaceUserPurchase> getMyMarketplacePurchases() {
         return createRequest().withUrlPath("/user/marketplace_purchases")

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

@@ -19,7 +19,7 @@
  *
  * @author Kohsuke Kawaguchi
  * @author Liam Newman
- * @see GitHubBuilder#withAbuseLimitHandler(AbuseLimitHandler) GitHubBuilder#withRateLimitHandler(AbuseLimitHandler)
+ * @see GitHubBuilder#withAbuseLimitHandler(GitHubAbuseLimitHandler)
  * @see GitHubRateLimitHandler
  */
 public abstract class GitHubAbuseLimitHandler extends GitHubConnectorResponseErrorHandler {
@@ -81,7 +81,8 @@ private boolean isForbidden(GitHubConnectorResponse connectorResponse) {
      *            the response from the GitHub connector
      * @return true if either "Retry-After" or "gh-limited-by" headers are present
      * @see <a href=
-     *      "https://docs.github.com/en/rest/using-the-rest-api/best-practices-for-using-the-rest-api?apiVersion=2022-11-28#handle-rate-limit-errors-appropriately</a>
+     *      "https://docs.github.com/en/rest/using-the-rest-api/best-practices-for-using-the-rest-api?apiVersion=2022-11-28#handle-rate-limit-errors-appropriately">GitHub
+     *      API Rate Limiting Documentation</a>
      */
     private boolean hasRetryOrLimitHeader(GitHubConnectorResponse connectorResponse) {
         return hasHeader(connectorResponse, "Retry-After") || hasHeader(connectorResponse, "gh-limited-by");

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

@@ -381,16 +381,16 @@ public String getApiUrl() {
 
     /**
      * Builds a {@link GitHubRequest}, sends the {@link GitHubRequest} to the server, and uses the {@link BodyHandler}
-     * to parse the response info and response body data into an instance of {@link T}.
+     * to parse the response info and response body data into an instance of {@code T}.
      *
      * @param <T>
      *            the type of the parse body data.
      * @param builder
      *            used to build the request that will be sent to the server.
      * @param handler
-     *            parse the response info and body data into a instance of {@link T}. If null, no parsing occurs and
+     *            parse the response info and body data into a instance of {@code T}. If null, no parsing occurs and
      *            {@link GitHubResponse#body()} will return null.
-     * @return a {@link GitHubResponse} containing the parsed body data as a {@link T}. Parsed instance may be null.
+     * @return a {@link GitHubResponse} containing the parsed body data as a {@code T}. Parsed instance may be null.
      * @throws IOException
      *             if an I/O Exception occurs
      */
@@ -402,16 +402,16 @@ public <T> GitHubResponse<T> sendRequest(@Nonnull GitHubRequest.Builder<?> build
 
     /**
      * Sends the {@link GitHubRequest} to the server, and uses the {@link BodyHandler} to parse the response info and
-     * response body data into an instance of {@link T}.
+     * response body data into an instance of {@code T}.
      *
      * @param <T>
      *            the type of the parse body data.
      * @param request
      *            the request that will be sent to the server.
      * @param handler
-     *            parse the response info and body data into a instance of {@link T}. If null, no parsing occurs and
+     *            parse the response info and body data into a instance of {@code T}. If null, no parsing occurs and
      *            {@link GitHubResponse#body()} will return null.
-     * @return a {@link GitHubResponse} containing the parsed body data as a {@link T}. Parsed instance may be null.
+     * @return a {@link GitHubResponse} containing the parsed body data as a {@code T}. Parsed instance may be null.
      * @throws IOException
      *             if an I/O Exception occurs
      */

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

@@ -57,7 +57,7 @@ public PagedIterator<T> _iterator(int pageSize) {
     }
 
     /**
-     * Eagerly walk {@link Iterable} and return the result in a {@link GitHubResponse} containing an array of {@link T}
+     * Eagerly walk {@link Iterable} and return the result in a {@link GitHubResponse} containing an array of {@code T}
      * items.
      *
      * @return the last response with an array containing all the results from all pages.

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

@@ -9,9 +9,9 @@
 
 // TODO: Auto-generated Javadoc
 /**
- * May be used for any item that has pagination information. Iterates over paginated {@link T} objects (not the items
- * inside the page). Also exposes {@link #finalResponse()} to allow getting a full {@link GitHubResponse<T>} after
- * iterating completes.
+ * May be used for any item that has pagination information. Iterates over paginated {@code T} objects (not the items
+ * inside the page). Also exposes {@link #finalResponse()} to allow getting a full {@link GitHubResponse}{@code <T>}
+ * after iterating completes.
  *
  * Works for array responses, also works for search results which are single instances with an array of items inside.
  *

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

@@ -19,7 +19,7 @@
  *
  * @author Kohsuke Kawaguchi
  * @author Liam Newman
- * @see GitHubBuilder#withRateLimitHandler(RateLimitHandler) GitHubBuilder#withRateLimitHandler(RateLimitHandler)
+ * @see GitHubBuilder#withRateLimitHandler(GitHubRateLimitHandler)
  * @see GitHubAbuseLimitHandler
  */
 public abstract class GitHubRateLimitHandler extends GitHubConnectorResponseErrorHandler {

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

@@ -72,15 +72,15 @@ class GitHubResponse<T> {
     }
 
     /**
-     * Parses a {@link GitHubConnectorResponse} body into a new instance of {@link T}.
+     * Parses a {@link GitHubConnectorResponse} body into a new instance of {@code T}.
      *
      * @param <T>
      *            the type
      * @param connectorResponse
      *            response info to parse.
      * @param type
      *            the type to be constructed.
-     * @return a new instance of {@link T}.
+     * @return a new instance of {@code T}.
      * @throws IOException
      *             if there is an I/O Exception.
      */
@@ -111,15 +111,15 @@ static <T> T parseBody(GitHubConnectorResponse connectorResponse, Class<T> type)
     }
 
     /**
-     * Parses a {@link GitHubConnectorResponse} body into a new instance of {@link T}.
+     * Parses a {@link GitHubConnectorResponse} body into a new instance of {@code T}.
      *
      * @param <T>
      *            the type
      * @param connectorResponse
      *            response info to parse.
      * @param instance
      *            the object to fill with data parsed from body
-     * @return a new instance of {@link T}.
+     * @return a new instance of {@code T}.
      * @throws IOException
      *             if there is an I/O Exception.
      */
@@ -207,7 +207,7 @@ public String header(String name) {
     }
 
     /**
-     * The body of the response parsed as a {@link T}.
+     * The body of the response parsed as a {@code T}.
      *
      * @return body of the response
      */

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

@@ -77,7 +77,7 @@ public void send() throws IOException {
      *            the type parameter
      * @param type
      *            the type
-     * @return an instance of {@link T}
+     * @return an instance of {@code T}
      * @throws IOException
      *             if the server returns 4xx/5xx responses.
      */
@@ -152,7 +152,7 @@ public static InputStream copyInputStream(InputStream inputStream) throws IOExce
     }
 
     /**
-     * Creates {@link PagedIterable <R>} from this builder using the provided {@link Consumer<R>}.
+     * Creates {@link PagedIterable <R>} from this builder using the provided {@link Consumer}{@code <R>}.
      * <p>
      * This method and the {@link PagedIterable <R>} do not actually begin fetching data until {@link Iterator#next()}
      * or {@link Iterator#hasNext()} are called.

src/test/java/org/kohsuke/github/AppTest.java

@@ -1413,7 +1413,7 @@ public void testIssueSearch() {
     /**
      * Test searching for pull requests.
      *
-     * @throws IOException
+     * @throws Exception
      *             the exception
      */
     @Test

src/test/java/org/kohsuke/github/GHRepositoryTest.java

@@ -1774,7 +1774,7 @@ public void cannotRetrievePermissionMaintainUser() throws IOException {
     /**
      * Test searching for pull requests.
      *
-     * @throws IOException
+     * @throws Exception
      *             the exception
      */
     @Test