Runtime.Version spec

[Pavel Rappo]

I have a couple of questions on the spec wording.

1.   * <li><p> <a name="build">{@code $BUILD}</a>, matching {@code
     * (0|[1-9][0-9]*)} --- The build number, incremented for each promoted
     * build.  {@code $BUILD} is reset to {@code 1} when any portion of {@code
     * $VNUM} is incremented. </p>

If the build number is reset to 1 each time $VNUM is changed, then what's
the purpose of build number 0? The spec allows it, but doesn't mention
how it is used.

2.   * comparison method.  The comparison methods {@link #compareTo(Version)
     * compareTo()} and {@link #compareToIgnoreOptional(Version)
     * compareToIgnoreOptional()} should be used consistently with the
     * corresponding methods {@link #equals(Object) equals()} and {@link
     * #equalsIgnoreOptional(Object) equalsIgnoreOptional()}.  </p>

The phrase "should be used consistently with" reads a bit strange to me. Can it
be the case that what was actually meant is that Version class guarantees
`compareTo` method is consistent with `equals` and `compareToIgnoreOptional` is
consistent with `equalsIgnoreOptional`. If so, then this is not the question of
how they are used (which is up to a caller), but of how they are implemented.
Here's what java.lang.Comparable has to say about it:

    * The natural ordering for a class {@code C} is said to be <i>consistent
    * with equals</i> if and only if {@code e1.compareTo(e2) == 0} has
    * the same boolean value as {@code e1.equals(e2)} for every
    * {@code e1} and {@code e2} of class {@code C}.
    ...
    * It is strongly recommended (though not required) that natural orderings be
    * consistent with equals.  This is so because sorted sets (and sorted maps)
    * without explicit comparators behave "strangely" when they are used with
    * elements (or keys) whose natural ordering is inconsistent with equals.
    ...
    * <p>It is strongly recommended, but <i>not</i> strictly required that
    * {@code (x.compareTo(y)==0) == (x.equals(y))}.  Generally speaking, any
    * class that implements the {@code Comparable} interface and violates
    * this condition should clearly indicate this fact.  The recommended
    * language is "Note: this class has a natural ordering that is
    * inconsistent with equals."

Maybe an explicit note could be moved to each of the comparison methods and/or
the top-level paragraph is rephrased a bit?

    * <p> This method provides ordering which is consistent with equals()

and

    * <p> This method provides ordering which is consistent with equalsIgnoreOptional()

3. The following explicit wordings do no harm, of course, but in my opinion they
bloat the spec.

In comparison methods:

    * <p> A version is not comparable to any other type of object.

If we make this class `final` as per [1], this might be removed.

In `equals` and `hashCode` methods:

     * <p> This method satisfies the general contract of the ... method.

Well, once again, no harm obviously, but being a subtype is kind of all
information we really need to know to infer that.

*. Now an API question.

Does it make any sense to make a stronger guarantee for Version.version method
to return an immutable list (as in List.of) rather than just an unmodifiable one?

Thanks.

--------------------------------------------------------------------------------
[1] http://mail.openjdk.java.net/pipermail/core-libs-dev/2017-March/046814.html