Only generate JavaDoc when explicitly requested, add more JavaDoc

.github/workflows/release.yml

@@ -24,13 +24,13 @@ jobs:
           cache: 'maven'
 
       - name: Unit Test
-        run: mvn clean test
+        run: mvn -pl core clean test
 
       - name: Build JAR-File
-        run: mvn clean package -DskipTests
+        run: mvn -pl core clean package -DskipTests
 
       - name: Generate JavaDoc
-        run: mvn javadoc:jar
+        run: mvn -pl core javadoc:jar
 
       - name: Upload Release
         uses: marvinpinto/action-automatic-releases@latest
@@ -41,5 +41,4 @@ jobs:
           title: "Release ${{ github.ref_name }}"
           files: |
             LICENSE
-            core/target/*-javadoc.jar
             core/target/*.jar

core/pom.xml

@@ -27,6 +27,7 @@
                 <executions>
                     <execution>
                         <id>attach-javadoc</id>
+                        <phase>none</phase> <!-- only produce JavaDoc explicitly with mvn javadoc:jar -->
                         <goals>
                             <goal>jar</goal>
                         </goals>

core/src/main/java/jjparse/Parsing.java

@@ -28,6 +28,12 @@
  */
 public abstract class Parsing<I> {
 
+    /**
+     * Creates an instance of this {@link Parsing} class and provides access to all {@link Parser}s and {@link Parser}
+     * combinators in that way.
+     */
+    public Parsing() { }
+
     /**
      * Represents the result of a parsing operation.
      * <br/><br/>
@@ -221,7 +227,6 @@ public final boolean isSuccess() {
          */
         public abstract boolean isFatal();
 
-
         @Override
         public <U> Result<U> map(final Function<T, U> function) {
             // Since failures never carry a value of their type parameter, this cast always succeeds.
@@ -241,7 +246,7 @@ public <U> Result<U> flatMap(final Function<T, Result<U>> function) {
         /**
          * Format an error message for the provided {@link Input} and {@link Description}.
          * @param input The related {@link Input} of the error message.
-         * @param description The {@link Description} of the {@link Parser} that failed.
+         * @param description The {@link Description} of the {@link Parsing.Parser} that failed.
          * @return A formatted error message that provides details about the location and kind of the error.
          */
         public static String format(final Input<?> input, final Description description) {
@@ -329,6 +334,8 @@ public abstract class Parser<T> implements Function<Input<I>, Result<T>> {
          * Applies this {@link Parser} to the provided {@link Input}, returning a {@link Result}.
          * @param input The {@link Input} which this {@link Parser} shall parse.
          * @return The {@link Result} of the parsing operation.
+         *
+         * @see Result
          */
         @Override
         public abstract Result<T> apply(final Input<I> input);
@@ -351,6 +358,7 @@ public Description description() {
          * @param function The {@link Function} which shall be applied to the {@link Result}s of this parser.
          * @return A {@link Parser} that parses the exact same language as this one, but with a transformed {@link Result}.
          * @param <U> The type of the transformed {@link Parser}.
+         * @see #flatMap
          */
         public final <U> Parser<U> map(final Function<T, U> function) {
             return new MapParser<>(this, function);
@@ -364,59 +372,184 @@ public final <U> Parser<U> map(final Function<T, U> function) {
          * @return A {@link Parser} that first applies this and then the one returned by the provided
          * {@link Function}.
          * @param <U> The type of the transformed {@link Parser}.
+         * @see #map
+         * @see #and
          */
         public final <U> Parser<U> flatMap(final Function<T, Parser<U>> function) {
             return new FlatMapParser<T, U>(this, function);
         }
 
+        /**
+         * Concatenates this and the provided {@link Parser} and returns a {@link Product} of the corresponding values
+         * on {@link Success}.
+         * @param right The second {@link Parser} which shall be appended to this {@link Parser}.
+         * @return A {@link Parser} which first parses this and then the provided one, returning the {@link Product} of
+         *         their returned values on {@link Success}.
+         * @param <U> The type of the second {@link Parser}'s {@link Result}.
+         * @see #keepLeft
+         * @see #keepRight
+         * @see #flatMap
+         * @see #or
+         * @see #sequence
+         */
         public final <U> Parser<Product<T, U>> and(final Parser<U> right) {
             return flatMap(first -> right.map(second -> new Product<>(first, second)));
         }
 
+        /**
+         * Concatenates this and the provided {@link Parser} but returns only the value parsed by this {@link Parser}.
+         * @param right The second {@link Parser} which shall be appended to this {@link Parser}.
+         * @return A {@link Parser} which first parses this and then the provided one, returning the value of this
+         *         {@link Parser} only.
+         * @param <U> The type of the second {@link Parser}'s {@link Result}.
+         * @see #keepRight
+         * @see #and
+         */
         public final <U> Parser<T> keepLeft(final Parser<U> right) {
             return flatMap(result -> right.map(ignore -> result));
         }
 
+        /**
+         * Concatenates this and the provided {@link Parser} but returns only the value parsed by the provided one.
+         * @param right The second {@link Parser} which shall be appended to this {@link Parser}.
+         * @return A {@link Parser} which first parses this and then the provided one, returning the value of the
+         *         provided {@link Parser} only.
+         * @param <U> The type of the second {@link Parser}'s {@link Result}.
+         * @see #keepLeft
+         * @see #and
+         */
         public final <U> Parser<U> keepRight(final Parser<U> right) {
             return flatMap(ignore -> right);
         }
 
+        /**
+         * Creates a {@link Parser} which first attempts to parse this {@link Parser} and, if this {@link Parser} fails
+         * with an {@link Error}, attempts to parse the exact same {@link Input} with the provided {@link Parser}.
+         * @param parser The alternative {@link Parser}.
+         * @return A {@link Parser} which first attempts to parse the {@link Input} with this and only then with the
+         *         provided {@link Parser}.
+         *
+         * @see #choice
+         * @see #and
+         */
         public final Parser<T> or(final Parser<T> parser) {
             return choice(this, parser);
         }
 
+        /**
+         * Creates a {@link Parser} which attempts to parse this {@link Parser} and only fails if this {@link Parser}
+         * aborts with an {@link Abort}.
+         * @return A {@link Parser} which optionally parses this {@link Parser}.
+         *
+         * @see Optional
+         * @see #repeat
+         */
         public final Parser<Optional<T>> optional() {
             return map(Optional::of).or(success(Optional::empty));
         }
 
+        /**
+         * Creates a {@link Parser} which applies this {@link Parser} arbitrarily many, including zero, times.
+         * @return A {@link Parser} which repeats this {@link Parser} arbitrarily many, including zero, times.
+         * @see #optional
+         * @see #repeat1
+         * @see #separate
+         * @see #separate1
+         */
         public final Parser<List<T>> repeat() {
             return new RepeatParser<>(this);
         }
 
+        /**
+         * Creates a {@link Parser} which applies this {@link Parser} arbitrarily many times but at least one time.
+         * @return A {@link Parser} which repeats this {@link Parser} arbitrarily many times but at least one time.
+         * @see #optional
+         * @see #repeat
+         * @see #separate
+         * @see #separate1
+         */
         public final Parser<List<T>> repeat1() {
             return this.and(repeat()).map(product -> product.map(Stream::of, List::stream).fold(Stream::concat).toList());
         }
 
+        /**
+         * Creates a {@link Parser} which parses this {@link Parser} (at least one time) interleaved with the provided
+         * separator {@link Parser}, only returning the values returned by this {@link Parser}. This is especially
+         * useful for {@link Input}s like comma separated values.
+         * @param separator The separator {@link Parser}.
+         * @return A {@link Parser} which parses this {@link Parser} interleaved with the provided separator
+         *         {@link Parser}.
+         * @see #repeat
+         * @see #repeat1
+         * @see #separate
+         * @see #chainLeft
+         * @see #chainLeft1
+         * @see #chainRight
+         * @see #chainRight1
+         */
         public final Parser<List<T>> separate1(final Parser<?> separator) {
             return this.and(separator.and(this).repeat()).map(product -> product.map(Stream::of, list -> list.stream().map(Product::second)).fold(Stream::concat).toList());
         }
 
+        /**
+         * Creates a {@link Parser} which parses this {@link Parser} (possibly zero times) interleaved with the provided
+         * separator {@link Parser}, only returning the values returned by this {@link Parser}. This is especially
+         * useful for {@link Input}s like comma separated values.
+         * @param separator The separator {@link Parser}.
+         * @return A {@link Parser} which parses this {@link Parser} interleaved with the provided separator
+         *         {@link Parser}.
+         * @see #repeat
+         * @see #repeat1
+         * @see #separate1
+         * @see #chainLeft
+         * @see #chainLeft1
+         * @see #chainRight
+         * @see #chainRight1
+         */
         public final Parser<List<T>> separate(final Parser<?> separator) {
             return separate1(separator).optional().map(result -> result.orElseGet(List::of));
         }
 
+        /**
+         * Creates a {@link Parser} which parses this {@link Parser} in between the two provided {@link Parser}s, only
+         * returning the value of this {@link Parser}.
+         * @param left The left of the two enclosing {@link Parser}s.
+         * @param right The right of the two enclosing {@link Parser}s.
+         * @return A {@link Parser} which parses this {@link Parser} in between the two provided {@link Parser}s.
+         * @see #and
+         */
         public final Parser<T> between(final Parser<?> left, final Parser<?> right) {
             return left.keepRight(this).keepLeft(right);
         }
 
+        /**
+         * Creates a {@link Parser} which behaves like this {@link Parser} except that the created {@link Parser} aborts
+         * with an {@link Abort} when this {@link Parser} fails with an {@link Error}. The effect of this is that
+         * backtracking does not extend over the created {@link Parser}. This is especially useful for the {@link Parser}
+         * right after a keyword {@link Parser}, to prevent backtracking over the keyword.
+         * @return A {@link Parser} which behaves like this {@link Parser}, but with backtracking disabled.
+         * @see #not
+         */
         public final Parser<T> commit() {
             return new CommitParser<>(this);
         }
 
+        /**
+         * Creates a {@link Parser} which attempts to not parse this {@link Parser}. That is to say, every
+         * {@link Failure} of this {@link Parser} is transformed into a {@link Success} and vice versa. The created
+         * {@link Parser} never consumes any {@link Input}.
+         * @return A {@link Parser} which ensures that this {@link Parser} is not applicable.
+         * @see #commit
+         */
         public final Parser<Void> not() {
             return new NegationParser(this);
         }
 
+        /**
+         * Creates a {@link Parser} which prints additional debug output to the standard output stream.
+         * @param name A human-readable name for this {@link Parser}.
+         * @return A {@link Parser} which behaves like this {@link Parser} but prints additional debug output.
+         */
         public final Parser<T> log(final String name) {
             return new LogParser<>(name, this);
         }