[v1.2.0] 补充Javadoc

.documentation/JAVADOC-README.md

@@ -0,0 +1,9 @@
+# GithubReleases4J Javadoc
+
+基于 [Github Pages](https://pages.github.com/) 搭建，请访问 [JavaDoc](https://CarmJos.github.io/GithubReleases4J) 。
+
+## 如何实现？
+
+若您也想通过 [Github Actions](https://docs.github.com/en/actions/learn-github-actions) 
+自动部署项目的Javadoc到 [Github Pages](https://pages.github.com/) ，
+可以参考我的文章 [《自动部署Javadoc到Github Pages》](https://pages.carm.cc/doc/javadoc-in-github.html) 。

pom.xml

@@ -14,7 +14,7 @@
 
     <groupId>cc.carm.lib</groupId>
     <artifactId>githubreleases4j</artifactId>
-    <version>1.1.0</version>
+    <version>1.2.0</version>
 
     <name>GithubReleases4J</name>
     <description>Github Releases for Java</description>

src/main/java/cc/carm/lib/githubreleases4j/GitHubHttpUtils.java

@@ -18,6 +18,7 @@ import java.util.stream.Collectors;
 public class GitHubHttpUtils {
 
 	private GitHubHttpUtils() {
+		// Should not be the instance or use by other codes.
 	}
 
 	protected static JSONObject getObject(@NotNull String urlString, @Nullable String token) throws IOException {

src/main/java/cc/carm/lib/githubreleases4j/GithubAsset.java

@@ -81,15 +81,34 @@ public class GithubAsset {
 		return GithubReleases4J.parseDate(getContents().getString("updated_at"));
 	}
 
+	/**
+	 * Download this asset to current path with original name.
+	 *
+	 * @return Downloaded file.
+	 * @throws IOException Throws when has any io exception
+	 */
 	public File download() throws IOException {
 		return download(null);
 	}
 
+	/**
+	 * Download this asset with provided path and name.
+	 *
+	 * @param path target path, e.g. "cache/build.zip"
+	 * @param options Copy options
+	 * @return Downloaded file.
+	 * @throws IOException Throws when has any io exception
+	 */
 	public File download(@Nullable String path, CopyOption... options) throws IOException {
 		path = path == null ? getName() : path;
 		return GitHubHttpUtils.download(getBrowserDownloadURL(), getSource().getAuthToken(), path, options);
 	}
 
+	/**
+	 * Get the uploader of this asset.
+	 *
+	 * @return The author user {@link GithubUser}
+	 */
 	public GithubUser getUploader() {
 		return Optional.ofNullable(getContents().getJSONObject("uploader"))
 				.map(GithubUser::of)

src/main/java/cc/carm/lib/githubreleases4j/GithubRelease.java

@@ -130,12 +130,22 @@ public class GithubRelease {
 		return getContents().getString("discussion_url");
 	}
 
+	/**
+	 * Get the author of this release.
+	 *
+	 * @return The author user {@link GithubUser}
+	 */
 	public GithubUser getAuthor() {
 		return Optional.ofNullable(getContents().getJSONObject("author"))
 				.map(GithubUser::of)
 				.orElse(null);
 	}
 
+	/**
+	 * Get the assets of this release.
+	 *
+	 * @return {@link GithubAsset}
+	 */
 	public List<GithubAsset> getAssets() {
 		JSONArray assetsArray = getContents().getJSONArray("assets");
 		if (assetsArray == null) return new ArrayList<>();

src/main/java/cc/carm/lib/githubreleases4j/GithubReleases4J.java

@@ -14,14 +14,31 @@ import java.util.List;
 import java.util.stream.Collectors;
 import java.util.stream.IntStream;
 
+/**
+ * GitHub Releases for Java
+ * <br>To provide an easy way to fetch updates and download assets.
+ * <br>Based on <a href="https://docs.github.com/cn/rest/reference/releases">GitHub REST API (Releases)</a> .
+ *
+ * @author CarmJos
+ */
 public class GithubReleases4J {
 
 	private GithubReleases4J() {
+		// Should not be the instance.
 	}
 
 	public static String GITHUB_API_URL = "https://api.github.com";
 	public static SimpleDateFormat GH_TIME_FORMAT = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss'Z'");
 
+	/**
+	 * List repository's current existing releases.
+	 *
+	 * @param owner      Repository's Owner
+	 * @param repository Repository's Name
+	 * @param token      OAuth Access Token
+	 *                   <br> Necessary when this repository is private.
+	 * @return {@link GithubRelease}
+	 */
 	public static @NotNull List<GithubRelease> listReleases(@NotNull String owner, @NotNull String repository,
 															@Nullable String token) {
 		try {
@@ -38,10 +55,28 @@ public class GithubReleases4J {
 		}
 	}
 
+	/**
+	 * List a public repository's current existing releases.
+	 *
+	 * @param owner      Repository's Owner
+	 * @param repository Repository's Name
+	 * @return {@link GithubRelease}
+	 */
 	public static @NotNull List<GithubRelease> listReleases(@NotNull String owner, @NotNull String repository) {
 		return listReleases(owner, repository, null);
 	}
 
+
+	/**
+	 * Get a repository's release by the id .
+	 *
+	 * @param owner      Repository's Owner
+	 * @param repository Repository's Name
+	 * @param releaseID  Release ID
+	 * @param token      OAuth Access Token
+	 *                   <br> Necessary when this repository is private.
+	 * @return {@link GithubRelease}
+	 */
 	public static @Nullable GithubRelease getRelease(@NotNull String owner, @NotNull String repository,
 													 @NotNull String releaseID, @Nullable String token) {
 
@@ -57,27 +92,70 @@ public class GithubReleases4J {
 
 	}
 
+
+	/**
+	 * Get a public repository's release by the id .
+	 *
+	 * @param owner      Repository's Owner
+	 * @param repository Repository's Name
+	 * @param releaseID  Release ID
+	 * @return {@link GithubRelease}
+	 */
 	public static @Nullable GithubRelease getRelease(@NotNull String owner, @NotNull String repository,
 													 @NotNull String releaseID) {
 		return getRelease(owner, repository, releaseID, null);
 	}
 
+
+	/**
+	 * Get a repository's release by the tag name .
+	 *
+	 * @param owner      Repository's Owner
+	 * @param repository Repository's Name
+	 * @param tagName    Release Tag Name
+	 * @param token      OAuth Access Token
+	 *                   <br> Necessary when this repository is private.
+	 * @return {@link GithubRelease}
+	 */
 	public static @Nullable GithubRelease getReleaseByTag(@NotNull String owner, @NotNull String repository,
 														  @NotNull String tagName, @Nullable String token) {
 		return getRelease(owner, repository, "tags/" + tagName, token);
 	}
 
-
+	/**
+	 * Get a public repository's release by the tag name .
+	 *
+	 * @param owner      Repository's Owner
+	 * @param repository Repository's Name
+	 * @param tagName    Release Tag Name
+	 * @return {@link GithubRelease}
+	 */
 	public static @Nullable GithubRelease getReleaseByTag(@NotNull String owner, @NotNull String repository,
 														  @NotNull String tagName) {
 		return getReleaseByTag(owner, repository, tagName, null);
 	}
 
+	/**
+	 * Get a repository's latest release.
+	 *
+	 * @param owner      Repository's Owner
+	 * @param repository Repository's Name
+	 * @param token      OAuth Access Token
+	 *                   <br> Necessary when this repository is private.
+	 * @return {@link GithubRelease}
+	 */
 	public static @Nullable GithubRelease getLatestRelease(@NotNull String owner, @NotNull String repository,
 														   @Nullable String token) {
 		return getRelease(owner, repository, "latest", token);
 	}
 
+	/**
+	 * Get a public repository's latest release.
+	 *
+	 * @param owner      Repository's Owner
+	 * @param repository Repository's Name
+	 * @return {@link GithubRelease}
+	 */
 	public static @Nullable GithubRelease getLatestRelease(@NotNull String owner, @NotNull String repository) {
 		return getLatestRelease(owner, repository, null);
 	}