feat: Javadocs for API classes (#13)

Author: SirYwell

build.gradle.kts

@@ -32,7 +32,9 @@ dependencies {
 java {
     withSourcesJar()
     withJavadocJar()
-    sourceCompatibility = JavaVersion.VERSION_11;
+    toolchain {
+        languageVersion.set(JavaLanguageVersion.of(11))
+    }
 }
 
 tasks {
@@ -55,17 +57,16 @@ tasks {
     compileTestJava{
         options.encoding = "UTF-8"
     }
+
+    javadoc {
+        (options as StandardJavadocDocletOptions).tags?.add("apiNote:a:API Note")
+    }
 }
 
 license {
     header(project.file("HEADER.txt"))
 }
 
-java {
-    withJavadocJar()
-    withSourcesJar()
-}
-
 publishData {
     useEldoNexusRepos()
     publishComponent("java")

src/main/java/de/eldoria/semvertools/Build.java

@@ -10,14 +10,30 @@
 
 import java.util.List;
 
+/**
+ * This represents the build part of a semantic version.
+ *
+ * @apiNote This interface is not meant to be implemented and might become {@code sealed} in future releases.
+ */
 @ApiStatus.NonExtendable
 public interface Build {
 
   static Build of(List<Identifier> identifiers) {
     return new BuildImpl(identifiers);
   }
 
+  /**
+   * Returns a string of the dot-separated identifiers of this build.
+   *
+   * @return a formatted build string.
+   */
   String asString();
 
+  /**
+   * Returns the list of identifiers represented by this build.
+   * The returned list is unmodifiable.
+   *
+   * @return the list of identifiers.
+   */
   List<Identifier> identifiers();
 }

src/main/java/de/eldoria/semvertools/Identifier.java

@@ -12,14 +12,32 @@
 import java.util.Optional;
 import java.util.function.Supplier;
 
+/**
+ * Represents either an alphanumeric or a numerical identifier.
+ * Identifiers are {@link Comparable} as described in <a href="https://semver.org/#spec-item-11">Item 11</a> of the spec.
+ *
+ * @apiNote This interface is not meant to be implemented and might become {@code sealed} in future releases.
+ */
 @ApiStatus.NonExtendable
 public interface Identifier extends Comparable<Identifier> {
 
+  /**
+   * Returns a numerical identifier representing the given non-negative integer.
+   *
+   * @param num a non-negative integer value.
+   * @return a numerical identifier for the given integer.
+   */
   static Identifier of(int num) {
     Integers.assertNonNegative(num);
     return new NumericalIdentifier(num);
   }
 
+  /**
+   * Returns an alphanumeric identifier for the given string.
+   *
+   * @param alphanumeric a string only containing alphanumeric characters.
+   * @return a new alphanumeric identifier.
+   */
   static Identifier of(String alphanumeric) {
     return Integers.parseNonNegativeInt(alphanumeric)
         .map(Identifier::of)
@@ -44,5 +62,11 @@ private static Supplier<Optional<Identifier>> alphanumeric(String value) {
     };
   }
 
+  /**
+   * Returns a {@link String} representation of this identifier. This normally equals
+   * the string it was parsed from.
+   *
+   * @return a string representation of this identifier.
+   */
   String asString();
 }

src/main/java/de/eldoria/semvertools/PreRelease.java

@@ -6,15 +6,40 @@
 
 package de.eldoria.semvertools;
 
+import org.jetbrains.annotations.ApiStatus;
+
 import java.util.List;
 
+/**
+ * This represents the pre-release part of a semantic version.
+ *
+ * @apiNote This interface is not meant to be implemented and might become {@code sealed} in future releases.
+ */
+@ApiStatus.NonExtendable
 public interface PreRelease extends Comparable<PreRelease> {
 
+  /**
+   * Creates a new pre-release with the given identifiers.
+   *
+   * @param identifiers the identifiers of the pre-release.
+   * @return a new pre-release.
+   */
   static PreRelease of(List<Identifier> identifiers) {
     return new PreReleaseImpl(identifiers);
   }
 
+  /**
+   * Returns a string of the dot-separated identifiers of this pre-release.
+   *
+   * @return a formatted pre-release string.
+   */
   String asString();
 
+  /**
+   * Returns the list of identifiers represented by this pre-release.
+   * The returned list is unmodifiable.
+   *
+   * @return the list of identifiers.
+   */
   List<Identifier> identifiers();
 }

src/main/java/de/eldoria/semvertools/SemanticVersion.java

@@ -13,48 +13,191 @@
 
 import java.util.Optional;
 
+/**
+ * A representation of a <a href="https://semver.org">Semantic Version</a>.
+ * <p>
+ * It contains the version core (major.minor.patch), pre-release and build.
+ * <p>
+ * The natural order of semantic versions is defined in <a href="https://semver.org/#spec-item-11">the spec</a>.
+ * @since 1.0.0
+ *
+ * @apiNote This interface is not meant to be implemented and might become {@code sealed} in future releases.
+ */
 @ApiStatus.NonExtendable
 public interface SemanticVersion extends Comparable<SemanticVersion> {
 
+  /**
+   * Creates a SemanticVersion with the given major, minor and patch versions.
+   *
+   * @param major the major version
+   * @param minor the minor version
+   * @param patch the patch version
+   * @return a SemanticVersion representing the version {@code major}.{@code minor}.{@code patch}.
+   */
   static SemanticVersion of(int major, int minor, int patch) {
     return new VersionCore(major, minor, patch);
   }
 
+  /**
+   * Parses a string into a full semantic version, including pre-releases and builds.
+   * <p>
+   * The given string must represent a valid semantic version, otherwise the parsing will fail.
+   *
+   * @param version the raw version string.
+   * @return the parsed version.
+   * @throws de.eldoria.semvertools.VersionParseException if the given string does not express
+   *                                                             a valid semantic version.
+   */
   static SemanticVersion parse(String version) {
     SemVerLexer lexer = new SemVerLexer();
     return new SemVerParser(version, lexer.lex(version)).parse();
   }
 
+  /**
+   * The major version of this semantic version.
+   * <p>
+   * This is a non-negative integer value.
+   *
+   * @return the major version.
+   */
   int major();
 
+  /**
+   * The minor version of this semantic version.
+   * <p>
+   * This is a non-negative integer value.
+   *
+   * @return the minor version.
+   */
   int minor();
 
+  /**
+   * The patch version of this semantic version.
+   * <p>
+   * This is a non-negative integer value.
+   *
+   * @return the patch version.
+   */
   int patch();
 
+  /**
+   * The pre-release version, if available.
+   * <p>
+   * If this semantic version does not have a pre-release version, {@link Optional#empty()} is returned.
+   *
+   * @return the pre-release version, wrapped into an {@link Optional}.
+   */
   Optional<PreRelease> preRelease();
 
+  /**
+   * The build metadata, if available.
+   * <p>
+   * If this semantic version does not have build metadata, {@link Optional#empty()} is returned.
+   *
+   * @return the build metadata, wrapped into an {@link Optional}.
+   */
   Optional<Build> build();
 
+  /**
+   * Returns a semantic version that only differs from this in its major version.
+   * <p>
+   * If the new major version is equal to the current major version, the returned semantic version
+   * is equal to this semantic version.
+   *
+   * @param major the new major version.
+   * @return the semantic version with the new major version.
+   */
   SemanticVersion withMajor(int major);
 
+  /**
+   * Increases the major version by 1.
+   * <p>
+   * This is equivalent to <pre>{@code
+   * SemanticVersion version = ...;
+   * version = version.withMajor(version.major() + 1);
+   * }</pre>
+   *
+   * @return the semantic version with a major version greater by 1 to this major version.
+   */
   default SemanticVersion increaseMajor() {
     return this.withMajor(this.major() + 1);
   }
 
+  /**
+   * Returns a semantic version that only differs from this in its minor version.
+   * <p>
+   * If the new minor version is equal to the current minor version, the returned semantic version
+   * is equal to this semantic version.
+   *
+   * @param minor the new minor version.
+   * @return the semantic version with the new minor version.
+   */
   SemanticVersion withMinor(int minor);
 
+  /**
+   * Increases the minor version by 1.
+   * <p>
+   * This is equivalent to <pre>{@code
+   * SemanticVersion version = ...;
+   * version = version.withMinor(version.minor() + 1);
+   * }</pre>
+   *
+   * @return the semantic version with a minor version greater by 1 to this minor version.
+   */
   default SemanticVersion increaseMinor() {
     return this.withMinor(this.minor() + 1);
   }
 
+  /**
+   * Returns a semantic version that only differs from this in its patch version.
+   * <p>
+   * If the new patch version is equal to the current patch version, the returned semantic version
+   * is equal to this semantic version.
+   *
+   * @param patch the new patch version.
+   * @return the semantic version with the new patch version.
+   */
   SemanticVersion withPatch(int patch);
 
+  /**
+   * Increases the patch version by 1.
+   * <p>
+   * This is equivalent to <pre>{@code
+   * SemanticVersion version = ...;
+   * version = version.withPatch(version.patch() + 1);
+   * }</pre>
+   *
+   * @return the semantic version with a minor version greater by 1 to this minor version.
+   */
   default SemanticVersion increasePatch() {
     return this.withPatch(this.patch() + 1);
   }
 
+  /**
+   * Returns a semantic version that only differs from this in its pre-release version.
+   * <p>
+   * If the new pre-release version is equal to the current pre-release version, the returned semantic version
+   * is equal to this semantic version.
+   * <p>
+   * If the new pre-release version is {@code null}, the returned semantic version
+   * won't contain a pre-release version.
+   *
+   * @param preRelease the new pre-release version.
+   * @return the semantic version with the new pre-release version.
+   */
   SemanticVersion withPreRelease(@Nullable PreRelease preRelease);
 
+  /**
+   * Returns a semantic version that only differs from this in its build metadata.
+   * <p>
+   * If the new build metadata is equal to the current build metadata, the returned semantic version
+   * is equal to this semantic version.
+   * <p>
+   * If the new build metadata is {@code null}, the returned semantic version won't contain build metadata.
+   *
+   * @param build the new build metadata.
+   * @return the semantic version with the new build metadata.
+   */
   SemanticVersion withBuild(@Nullable Build build);
 
   /**
@@ -78,4 +221,23 @@ default boolean precedes(SemanticVersion other) {
   default boolean succeeds(SemanticVersion other) {
     return compareTo(other) > 0;
   }
+
+  /**
+   * Returns whether this semantic version is equal to the given object.
+   * <p>
+   * <b>Note:</b> Two semantic versions are considered equal if major version, minor version,
+   * patch version, pre-release version and build metadata are equal. This differs from
+   * {@link SemanticVersion#compareTo(Object)}, as build metadata is considered
+   * for the {@code equals} method only. If you want to check if two semantic versions are equal, you can:
+   * <ul>
+   * <li>strip the build metadata before using this method</li>
+   * <li>use {@code versionA.compareTo(versionB) == 0}</li>
+   * <li>use {@code !(versionA.succeeds(versionB) || versionA.precedes(versionB))}</li>
+   * </ul>
+   *
+   * @param o the object to compare to.
+   * @return {@code true} if both semantic versions are equal.
+   */
+  @Override
+  boolean equals(Object o);
 }

src/main/java/de/eldoria/semvertools/VersionParseException.java

@@ -6,12 +6,26 @@
 
 package de.eldoria.semvertools;
 
+/**
+ * This exception is thrown to indicate that parsing a semantic version was not successful.
+ */
 public class VersionParseException extends RuntimeException {
 
+  /**
+   * Creates a new VersionParseException with the specified message.
+   *
+   * @param message the message describing the exception details.
+   */
   public VersionParseException(String message) {
     super(message);
   }
 
+  /**
+   * Creates a new VersionParseException with the specified message and the specified cause.
+   *
+   * @param message the message describing the exception details.
+   * @param cause   the Throwable causing this exception.
+   */
   public VersionParseException(String message, Throwable cause) {
     super(message, cause);
   }