From 9274c8be3a373c8cea67ad34933d40d7f0bc55d9 Mon Sep 17 00:00:00 2001 From: rnveach Date: Tue, 25 Feb 2025 20:10:25 -0500 Subject: [PATCH] fixed various javadoc issues --- .../org/kohsuke/github/AbstractBuilder.java | 24 +++++++++---------- .../kohsuke/github/GHDiscussionBuilder.java | 4 ++-- .../org/kohsuke/github/GHLabelBuilder.java | 4 ++-- .../java/org/kohsuke/github/GHRateLimit.java | 4 ++-- .../github/GHRepositoryVariableBuilder.java | 2 +- src/main/java/org/kohsuke/github/GHUser.java | 4 ++-- src/main/java/org/kohsuke/github/GitHub.java | 4 ++-- .../github/GitHubAbuseLimitHandler.java | 5 ++-- .../java/org/kohsuke/github/GitHubClient.java | 12 +++++----- .../github/GitHubPageContentsIterable.java | 2 +- .../kohsuke/github/GitHubPageIterator.java | 6 ++--- .../github/GitHubRateLimitHandler.java | 2 +- .../org/kohsuke/github/GitHubResponse.java | 10 ++++---- .../java/org/kohsuke/github/Requester.java | 4 ++-- src/test/java/org/kohsuke/github/AppTest.java | 2 +- .../org/kohsuke/github/GHRepositoryTest.java | 2 +- 16 files changed, 46 insertions(+), 45 deletions(-) diff --git a/src/main/java/org/kohsuke/github/AbstractBuilder.java b/src/main/java/org/kohsuke/github/AbstractBuilder.java index 8a581270e6..c91043cd19 100644 --- a/src/main/java/org/kohsuke/github/AbstractBuilder.java +++ b/src/main/java/org/kohsuke/github/AbstractBuilder.java @@ -27,19 +27,19 @@ * set().otherName(value); * *

- * 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()}. *

*

- * 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 * Final return type built by this builder returned when {@link #done()}} is called. * @param - * 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 extends GitHubInteractiveObject implements GitHubRequestBuilderDone { @@ -68,7 +68,7 @@ abstract class AbstractBuilder 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 diff --git a/src/main/java/org/kohsuke/github/GHDiscussionBuilder.java b/src/main/java/org/kohsuke/github/GHDiscussionBuilder.java index 19097c09fc..39dfd287d1 100644 --- a/src/main/java/org/kohsuke/github/GHDiscussionBuilder.java +++ b/src/main/java/org/kohsuke/github/GHDiscussionBuilder.java @@ -10,7 +10,7 @@ * Base class for creating or updating a discussion. * * @param - * 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 extends AbstractBuilder { * * @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. diff --git a/src/main/java/org/kohsuke/github/GHLabelBuilder.java b/src/main/java/org/kohsuke/github/GHLabelBuilder.java index 3803a7de8e..62a5c2ce7e 100644 --- a/src/main/java/org/kohsuke/github/GHLabelBuilder.java +++ b/src/main/java/org/kohsuke/github/GHLabelBuilder.java @@ -10,7 +10,7 @@ * The Class GHLabelBuilder. * * @param - * 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 extends AbstractBuilder { * * @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 diff --git a/src/main/java/org/kohsuke/github/GHRateLimit.java b/src/main/java/org/kohsuke/github/GHRateLimit.java index 51faa4c10e..b7ca406a72 100644 --- a/src/main/java/org/kohsuke/github/GHRateLimit.java +++ b/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. diff --git a/src/main/java/org/kohsuke/github/GHRepositoryVariableBuilder.java b/src/main/java/org/kohsuke/github/GHRepositoryVariableBuilder.java index 62af8140d8..0bbd874288 100644 --- a/src/main/java/org/kohsuke/github/GHRepositoryVariableBuilder.java +++ b/src/main/java/org/kohsuke/github/GHRepositoryVariableBuilder.java @@ -17,7 +17,7 @@ public class GHRepositoryVariableBuilder extends AbstractBuilder listGists() { * @return The LDAP information * @throws IOException * the io exception - * @see Github + * @see Github * LDAP */ public Optional getLdapDn() throws IOException { diff --git a/src/main/java/org/kohsuke/github/GitHub.java b/src/main/java/org/kohsuke/github/GitHub.java index a7f6605125..8ef21e2cd0 100644 --- a/src/main/java/org/kohsuke/github/GitHub.java +++ b/src/main/java/org/kohsuke/github/GitHub.java @@ -684,8 +684,8 @@ public Map getMyOrganizations() throws IOException { * OAuth Apps must authenticate using an OAuth token. * * @return the paged iterable of GHMarketplaceUserPurchase - * @see Get a user's - * Marketplace purchases + * @see Get a + * user's Marketplace purchases */ public PagedIterable getMyMarketplacePurchases() { return createRequest().withUrlPath("/user/marketplace_purchases") diff --git a/src/main/java/org/kohsuke/github/GitHubAbuseLimitHandler.java b/src/main/java/org/kohsuke/github/GitHubAbuseLimitHandler.java index 30f3193c2f..84dd8c48e9 100644 --- a/src/main/java/org/kohsuke/github/GitHubAbuseLimitHandler.java +++ b/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 + * "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 */ private boolean hasRetryOrLimitHeader(GitHubConnectorResponse connectorResponse) { return hasHeader(connectorResponse, "Retry-After") || hasHeader(connectorResponse, "gh-limited-by"); diff --git a/src/main/java/org/kohsuke/github/GitHubClient.java b/src/main/java/org/kohsuke/github/GitHubClient.java index a8cf296935..f669280b4d 100644 --- a/src/main/java/org/kohsuke/github/GitHubClient.java +++ b/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 * 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 GitHubResponse 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 * 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 */ diff --git a/src/main/java/org/kohsuke/github/GitHubPageContentsIterable.java b/src/main/java/org/kohsuke/github/GitHubPageContentsIterable.java index 0af3fe96c7..3239f6f71a 100644 --- a/src/main/java/org/kohsuke/github/GitHubPageContentsIterable.java +++ b/src/main/java/org/kohsuke/github/GitHubPageContentsIterable.java @@ -57,7 +57,7 @@ public PagedIterator _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. diff --git a/src/main/java/org/kohsuke/github/GitHubPageIterator.java b/src/main/java/org/kohsuke/github/GitHubPageIterator.java index 975a010a90..23a6198445 100644 --- a/src/main/java/org/kohsuke/github/GitHubPageIterator.java +++ b/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} 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 } + * after iterating completes. * * Works for array responses, also works for search results which are single instances with an array of items inside. * diff --git a/src/main/java/org/kohsuke/github/GitHubRateLimitHandler.java b/src/main/java/org/kohsuke/github/GitHubRateLimitHandler.java index 8cb5911266..ef7c662d3d 100644 --- a/src/main/java/org/kohsuke/github/GitHubRateLimitHandler.java +++ b/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 { diff --git a/src/main/java/org/kohsuke/github/GitHubResponse.java b/src/main/java/org/kohsuke/github/GitHubResponse.java index fc8cb02f28..defc094b64 100644 --- a/src/main/java/org/kohsuke/github/GitHubResponse.java +++ b/src/main/java/org/kohsuke/github/GitHubResponse.java @@ -72,7 +72,7 @@ class GitHubResponse { } /** - * 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 * the type @@ -80,7 +80,7 @@ class GitHubResponse { * 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,7 +111,7 @@ static T parseBody(GitHubConnectorResponse connectorResponse, Class 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 * the type @@ -119,7 +119,7 @@ static T parseBody(GitHubConnectorResponse connectorResponse, Class type) * 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 */ diff --git a/src/main/java/org/kohsuke/github/Requester.java b/src/main/java/org/kohsuke/github/Requester.java index 1e5e987657..ad65f1a2d1 100644 --- a/src/main/java/org/kohsuke/github/Requester.java +++ b/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 } from this builder using the provided {@link Consumer}. + * Creates {@link PagedIterable } from this builder using the provided {@link Consumer}{@code }. *

* This method and the {@link PagedIterable } do not actually begin fetching data until {@link Iterator#next()} * or {@link Iterator#hasNext()} are called. diff --git a/src/test/java/org/kohsuke/github/AppTest.java b/src/test/java/org/kohsuke/github/AppTest.java index 9f98835db3..ec2938ae02 100755 --- a/src/test/java/org/kohsuke/github/AppTest.java +++ b/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 diff --git a/src/test/java/org/kohsuke/github/GHRepositoryTest.java b/src/test/java/org/kohsuke/github/GHRepositoryTest.java index 23fd710dbf..0d1f6e4590 100644 --- a/src/test/java/org/kohsuke/github/GHRepositoryTest.java +++ b/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