Add JavaDoc for the default constructor of the 'Description' and 'Emp…

…ty' class, add JavaDoc for the different 'Input' classes and delete the unused 'FilterInput' class

core/src/main/java/jjparse/description/Description.java

@@ -36,6 +36,11 @@
  */
 public sealed abstract class Description permits Choice, Literal, Negation, RegExp, Sequence, Empty {
 
+    /**
+     * Construct a new {@link Description}.
+     */
+    public Description() { }
+
     /**
      * Produces a {@link String} that explains what a corresponding {@link Parser} would expect according to this
      * {@link Description}.

core/src/main/java/jjparse/description/Empty.java

@@ -14,6 +14,11 @@
  */
 public final class Empty extends Description {
 
+    /**
+     * Constructs a new {@link Empty} {@link Description}.
+     */
+    public Empty() { }
+
     @Override
     public Optional<String> describe() {
         return Optional.empty();

core/src/main/java/jjparse/input/CharacterInput.java

@@ -1,6 +1,5 @@
 package jjparse.input;
 
-import java.util.Arrays;
 import java.util.NoSuchElementException;
 
 /**
@@ -18,14 +17,19 @@
  */
 public final class CharacterInput extends Input<Character> implements CharSequence {
 
+    /** A cache of line offsets to efficiently compute the line and column numbers of a {@link Position}. */
     private final int[] lines;
 
+    /** The underlying {@link CharSequence} of this {@link CharacterInput}. */
     private final CharSequence sequence;
 
+    /** The offset in characters that denotes the start of the subsequence in the underlying {@link CharSequence}. */
     private final int offset;
 
+    /** The length of the subsequence that is denoted by the offset. */
     private final int length;
 
+    /** The current {@link Position} of this {@link CharacterInput}. */
     private final CodePointPosition position;
 
     /**

core/src/main/java/jjparse/input/Input.java

@@ -10,7 +10,6 @@
 import java.util.Iterator;
 import java.util.NoSuchElementException;
 import java.util.Objects;
-import java.util.function.Predicate;
 import java.util.stream.IntStream;
 import java.util.stream.Stream;
 import java.util.stream.StreamSupport;
@@ -77,35 +76,6 @@ public final boolean nonEmpty() {
      */
     public abstract Position position();
 
-    /**
-     * Filters this {@link Input} by skipping all elements for which the given {@link Predicate} does not hold. The
-     * {@link Position}s returned by the filtered {@link Input} are not affected by this operation. That is, all
-     * elements retain their original {@link Position}s from this {@link Input}.
-     * @param predicate The {@link Predicate} that shall be used as filter. Whenever this {@link Predicate} returns
-     *                  {@code false} for an element, it is skipped and not included in the final {@link Input}.
-     * @return An {@link Input} containing all elements of this {@link Input} except for those elements for which the
-     *         provided {@link Predicate} does not hold.
-     * @see #position()
-     */
-    public final Input<T> filter(final Predicate<T> predicate) {
-        return new FilterInput<>(this, predicate);
-    }
-
-    /**
-     * Skips the leading elements of this {@link Input} as long as the provided {@link Predicate} holds.
-     * @param predicate The {@link Predicate} that indicates whether an element shall be skipped or not. 
-     * @return The remaining {@link Input} after skipping the leading elements of this {@link Input}.
-     */
-    public final Input<T> skip(final Predicate<T> predicate) {
-        Input<T> input = this;
-
-        while (input.nonEmpty() && predicate.test(input.head())) {
-            input = input.tail();
-        }
-
-        return input;
-    }
-
     /**
      * Represents an offset within this {@link Input}. Since the unit of this offset depends on the element type of
      * this {@link Input}, this class depends on the specific {@link Input} instance. Also note, that this offset may

core/src/main/java/jjparse/input/StreamInput.java

@@ -3,22 +3,50 @@
 import java.util.NoSuchElementException;
 import java.util.stream.Stream;
 
+/**
+ * A lazily evaluated {@link Input} for {@link Stream}s of arbitrary elements. {@link Position}s returned by this
+ * {@link Input} reflect the order in which the elements are retrieved from the {@link Stream} using {@link Stream#findFirst()}.
+ * @param <T> The element type of the {@link Stream}.
+ *
+ * @author Björn Lötters
+ *
+ * @see Input
+ * @see Position
+ * @see Stream
+ * @see Stream#findFirst
+ */
 public final class StreamInput<T> extends Input<T> {
 
+    /** The {@link Stream} internally used as the source. */
     private final Stream<T> stream;
 
+    /** The current offset in the {@link Stream} (i.e., the number of elements already retrieved). */
     private final int offset;
 
+    /** A cache of the current element in this {@link StreamInput}. */
     private T head = null;
+
+    /** A cache for the information whether this {@link StreamInput} is empty or not. */
     private boolean isEmpty = false;
+
+    /** A flag that indicates whether the internal cache is already initialized or not. */
     private boolean initialized = false;
 
+    /**
+     * Constructs a new {@link StreamInput}.
+     * @param name A human-readable name for this {@link StreamInput}.
+     * @param stream The underlying {@link Stream} for this {@link StreamInput}.
+     * @param offset The current offset in the underlying {@link Stream} (i.e., the number of elements already retrieved).
+     */
     StreamInput(final String name, final Stream<T> stream, final int offset) {
         super(name);
         this.stream = stream;
         this.offset = offset;
     }
 
+    /**
+     * Initializes the internal cache if this has not yet been done.
+     */
     private void initialize() {
         if (!initialized) {
             initialized = true;