#274: Updated JavaDoc.

core/src/main/java/io/parsingdata/metal/expression/value/BinaryValueExpression.java

@@ -33,16 +33,16 @@
 /**
  * Base class for {@link ValueExpression}s with two operands.
  * <p>
- * A BinaryValueExpression implements a ValueExpression that has two operands:
+ * A BinaryValueExpression implements a ValueExpression that has two fields:
  * <code>lefts</code> and <code>rights</code> (both {@link ValueExpression}s).
- * Both operands are themselves first evaluated. If at least one of the
- * operands evaluates to {@link Optional#empty()}, the result of the
- * ValueExpression itself will be empty as well.
+ * Both fields are first evaluated. If at least one of the operands evaluates to
+ * {@link Optional#empty()}, the result of the ValueExpression itself will be
+ * empty as well.
  * <p>
- * For lists, values with the same index are evaluated in this manner. If
- * lists are of unequal length, the result is a list with evaluated values the
- * same size as the shortest list, appended with empty values to match the
- * size of the longest list.
+ * For lists, values with the same index are evaluated in this manner. If lists
+ * are of unequal length, the result is a list with evaluated values the same
+ * size as the shortest list, appended with empty values to match the size of the
+ * longest list.
  * <p>
  * To implement a BinaryValueExpression, only the
  * {@link #eval(Value, Value, ParseState, Encoding)} method must be implemented,

core/src/main/java/io/parsingdata/metal/expression/value/Const.java

@@ -27,7 +27,7 @@
 /**
  * A {@link ValueExpression} representing a constant value.
  * <p>
- * Const has a single operand <code>value</code> (a {@link Value}). When
+ * Const has a single field called <code>value</code> (a {@link Value}). When
  * evaluated, this value is returned.
  */
 public class Const implements ValueExpression {

core/src/main/java/io/parsingdata/metal/expression/value/Elvis.java

@@ -34,13 +34,13 @@
  * A {@link ValueExpression} that implements the Elvis operator:
  * <pre>?:</pre>.
  * <p>
- * An Elvis expression has two operands: <code>lefts</code> and
- * <code>rights</code> (both {@link ValueExpression}s). Both operands are
- * evaluated. The return value is a list with the size of the longest list
- * returned by the two evaluations. At each index, the value at that index in
- * the result returned by evaluating <code>lefts</code> is placed, except if it
- * does not exist or is {@link Optional#empty()}, in which case the value at
- * that index in the result returned by evaluating rights is placed there.
+ * An Elvis expression has two fields: <code>lefts</code> and <code>rights</code>
+ * (both {@link ValueExpression}s). Both fields are evaluated. The return value is
+ * a list with the size of the longest list returned by the two evaluations. At
+ * each index, the value at that index in the result returned by evaluating
+ * <code>lefts</code> is placed, except if it does not exist or is {@link Optional#empty()},
+ * in which case the value at that index in the result returned by evaluating rights is
+ * placed there.
  */
 public class Elvis implements ValueExpression {
 

core/src/main/java/io/parsingdata/metal/expression/value/Expand.java

@@ -33,12 +33,12 @@
  * A {@link ValueExpression} that expands a result by copying and concatenating
  * it a specified amount of times.
  * <p>
- * An Expand expression has two operands: <code>bases</code> and
- * <code>count</code> (both {@link ValueExpression}s). Both operands are
- * evaluated. An <code>IllegalStateException</code> is thrown if evaluating
- * <code>count</code> yields more than a single value. Multiple copies of the
- * result of evaluating <code>bases</code> are concatenated. The amount of copies
- * equals the result of evaluating <code>count</code>.
+ * An Expand expression has two fields: <code>bases</code> and <code>count</code>
+ * (both {@link ValueExpression}s). Both fields are evaluated. An
+ * <code>IllegalStateException</code> is thrown if evaluating <code>count</code> yields
+ * more than a single value. Multiple copies of the result of evaluating
+ * <code>bases</code> are concatenated. The amount of copies equals the result of
+ * evaluating <code>count</code>.
  */
 public class Expand implements ValueExpression {
 

core/src/main/java/io/parsingdata/metal/expression/value/Fold.java

@@ -31,18 +31,17 @@
 import io.parsingdata.metal.encoding.Encoding;
 
 /**
- * Base class for {@link ValueExpression} implementations of the Fold
- * operation.
+ * Base class for {@link ValueExpression} implementations of the Fold operation.
  * <p>
- * Fold has three operands: <code>values</code> (a {@link ValueExpression}),
+ * Fold has three fields: <code>values</code> (a {@link ValueExpression}),
  * <code>reducer</code> (a {@link BinaryOperator}) and <code>initial</code> (a
- * {@link ValueExpression}). First <code>initial</code> is evaluated. If it
- * does not return a single value, the final result is an empty list. Next,
- * <code>values</code> is evaluated and its result is passed to the abstract
- * {@link #prepareValues(ImmutableList)} method. The returned list is prefixed
- * by the value returned by evaluating <code>initial</code>. On this list, the
- * <code>reducer</code> is applied to the first two values until a single
- * value remains, which is then returned.
+ * {@link ValueExpression}). First <code>initial</code> is evaluated. If it does not
+ * return a single value, the final result is an empty list. Next, <code>values</code>
+ * is evaluated and its result is passed to the abstract
+ * {@link #prepareValues(ImmutableList)} method. The returned list is prefixed by the
+ * value returned by evaluating <code>initial</code>. On this list, the
+ * <code>reducer</code> is applied to the first two values until a single value remains,
+ * which is then returned.
  */
 public abstract class Fold implements ValueExpression {
 

core/src/main/java/io/parsingdata/metal/expression/value/Reverse.java

@@ -30,9 +30,9 @@
 /**
  * A {@link ValueExpression} that reverses the results of its operand.
  * <p>
- * Reverse has a single operand <code>values</code> (a
- * {@link ValueExpression}). When evaluated, it evaluates <code>values</code>
- * and then reverses and returns the result.
+ * Reverse has a single field <code>values</code> (a {@link ValueExpression}).
+ * When evaluated, it evaluates <code>values</code> and then reverses and returns
+ * the result.
  */
 public class Reverse implements ValueExpression {
 

core/src/main/java/io/parsingdata/metal/expression/value/UnaryValueExpression.java

@@ -33,16 +33,13 @@
 /**
  * Base class for {@link ValueExpression}s with one operand.
  * <p>
- * A UnaryValueExpression implements a ValueExpression that has a single
- * <code>operands</code> field (a {@link ValueExpression}).
- * <code>operands</code>is first evaluated. If it evaluates to
- * {@link Optional#empty()}, the result of the ValueExpression itself will be
- * that as well.
+ * A UnaryValueExpression implements a ValueExpression that has a single <code>operands</code>
+ * field (a {@link ValueExpression}). <code>operands</code> is first evaluated. If it evaluates
+ * to {@link Optional#empty()}, the result of the ValueExpression itself will be that as well.
  * <p>
- * To implement a UnaryValueExpression, only the
- * {@link #eval(Value, ParseState, Encoding)} must be implemented, handling
- * the case of evaluating one value. This base class takes care of evaluating
- * the operand and handling list semantics.
+ * To implement a UnaryValueExpression, only the {@link #eval(Value, ParseState, Encoding)}
+ * must be implemented, handling the case of evaluating one value. This base class takes care
+ * of evaluating the field and handling list semantics.
  *
  * @see BinaryValueExpression
  */

core/src/main/java/io/parsingdata/metal/expression/value/ValueExpression.java

@@ -26,12 +26,11 @@
  * Interface for all ValueExpression implementations.
  * <p>
  * A ValueExpression is an expression that is evaluated by executing its
- * {@link #eval(ParseState, Encoding)} method. It yields a list of
- * {@link Value} objects encapsulated in {@link Optional} objects (to guard
- * against <code>null</code>s).
+ * {@link #eval(ParseState, Encoding)} method. It yields a list of {@link Value} objects
+ * encapsulated in {@link Optional} objects (to guard against <code>null</code>s).
  * <p>
- * As context, it receives the current <code>parseState</code> object that as
- * well as the current <code>encoding</code> object.
+ * As context, it receives the current {@link ParseState} object that as well as
+ * the current {@link Encoding} object.
  */
 @FunctionalInterface
 public interface ValueExpression {

core/src/main/java/io/parsingdata/metal/expression/value/reference/CurrentIteration.java

@@ -46,6 +46,9 @@
  * A {@link ValueExpression} that represents the zero-based current iteration in an
  * iterable {@link Token} (when {@link Token#isIterable()} returns true, e.g. when
  * inside a {@link Rep}, {@link RepN}) or {@link While}).
+ *
+ * The <code>level</code> field must evaluate to a single value that represents the
+ * relative nesting level from the current parsing position in the {@link ParseState}.
  */
 public class CurrentIteration implements ValueExpression {
 

core/src/main/java/io/parsingdata/metal/expression/value/reference/CurrentOffset.java

@@ -29,8 +29,7 @@
 import io.parsingdata.metal.expression.value.ValueExpression;
 
 /**
- * A {@link ValueExpression} that represents the current offset in the
- * {@link ParseState}.
+ * A {@link ValueExpression} that represents the current offset in the {@link ParseState}.
  */
 public class CurrentOffset implements ValueExpression {
 

core/src/main/java/io/parsingdata/metal/expression/value/reference/Nth.java

@@ -39,7 +39,7 @@
 /**
  * A {@link ValueExpression} that returns an indexed list of {@link Value}s.
  * <p>
- * The Nth ValueExpression has two operands, <code>values</code> and
+ * The Nth ValueExpression has two fields, <code>values</code> and
  * <code>indices</code> (both {@link ValueExpression}s). Both operands are
  * evaluated. Next, the resulting values of evaluating <code>indices</code> is
  * used as a list of integer indices into the results of evaluating

core/src/main/java/io/parsingdata/metal/expression/value/reference/Ref.java

@@ -41,8 +41,9 @@
  * state that match a provided object. This class only has a private
  * constructor and instead must be instantiated through one of its subclasses:
  * {@link NameRef} (to match on name) and {@link DefinitionRef} (to match on
- * definition). A limit argument may be provided to specify an upper bound to
- * the amount of returned results.
+ * definition). The <code>limit</code> field is optional and is used to specify
+ * an upper bound to the amount of returned results.
+ *
  * @param <T> The type of reference to match on.
  */
 public class Ref<T> implements ValueExpression {

core/src/main/java/io/parsingdata/metal/expression/value/reference/Self.java

@@ -28,8 +28,7 @@
 import io.parsingdata.metal.expression.value.ValueExpression;
 
 /**
- * A {@link ValueExpression} that represents the
- * {@link io.parsingdata.metal.expression.value.Value} most recently added to
+ * A {@link ValueExpression} that represents the {@link Value} most recently added to
  * the parse state.
  */
 public class Self implements ValueExpression {