Edit version comparison

maven-resolver-util/src/main/java/org/eclipse/aether/util/version/package-info.java

@@ -21,22 +21,22 @@
  * Version scheme for parsing/comparing versions and utility classes.
  * <p>
  * Contains the "generic" scheme {@link org.eclipse.aether.util.version.GenericVersionScheme}
- * that serves the purpose of "factory" (and/or parser) for all corresponding elements (all those are package private).
+ * that serves as a "factory" (and/or parser) for corresponding package private classes.
  * <p>
- * On the other hand, the {@link org.eclipse.aether.util.version.UnionVersionRange} is universal implementation of
+ * On the other hand, the {@link org.eclipse.aether.util.version.UnionVersionRange} is a universal implementation of
  * "unions" of various {@link org.eclipse.aether.version.VersionRange} instances.
  * <p>
- * Below is the <em>Generic Version Spec</em> described:
- * <p>
- * Version string is parsed into version according to these rules:
+ * A version string is parsed according to the
+ * <a href='https://maven.apache.org/pom.html#Version_Order_Specification'>Version Order Specification</a>.
+ * These rules are summarized here:
  * <ul>
  *     <li>The version string is parsed into segments, from left to right.</li>
  *     <li>Segments are explicitly delimited by a single {@code "." (dot)}, {@code "-" (hyphen)}, or {@code "_" (underscore)} character.</li>
  *     <li>Segments are implicitly delimited by a transition between ASCII digits and non-digits.</li>
  *     <li>Segments are classified as numeric, string, qualifiers (special case of string), and min/max.</li>
  *     <li>Numeric segments are composed of the ASCII digits 0-9. Non-ASCII digits are treated as letters.
  *     <li>Numeric segments are sorted numerically, ascending.</li>
- *     <li>Non-numeric segments may be qualifiers (predefined) or strings (non-empty letter sequence). All of them are interpreted as being case-insensitive in terms of the ROOT locale.</li>
+ *     <li>Non-numeric segments may be qualifiers (predefined) or strings (non-empty letter sequences). All of them are interpreted as being case-insensitive in the ROOT locale.</li>
  *     <li>Qualifier segments (strings listed below) and their sort order (ascending) are:
  *         <ul>
  *             <li>"alpha" (== "a" when immediately followed by number)</li>
@@ -52,16 +52,16 @@
  *     <li>There are two special segments, {@code "min"} and {@code "max"} that represent absolute minimum and absolute maximum in comparisons. They can be used only as the trailing segment.</li>
  *     <li>As last step, trailing "zero segments" are trimmed. Similarly, "zero segments" positioned before numeric and non-numeric transitions (either explicitly or implicitly delimited) are trimmed.</li>
  *     <li>When trimming, "zero segments" are qualifiers {@code "ga"}, {@code "final"}, {@code "release"} only if being last (right-most) segment, empty string and "0" always.</li>
- *     <li>In comparison of same kind segments, the given type of segment determines comparison rules.</li>
- *     <li>In comparison of different kind of segments, following applies: {@code max > numeric > string > qualifier > min}.</li>
+ *     <li>When comparing the same kind of segments, the type of segment determines comparison rules.</li>
+ *     <li>When comparing different kinds of segments, the following applies: {@code max > numeric > string > qualifier > min}.</li>
  *     <li>Any version can be considered to have an infinite number of invisible trailing "zero segments", for the purposes of comparison (in other words, "1" == "1.0.0.0.0.0.0.0.0....")</li>
  *     <li>It is common that a version identifier starts with numeric segment (consider this "best practice").</li>
  * </ul>
  * <p>
  * Note: this version spec does not document (or cover) many corner cases that we believe are "atypical" or not
- * used commonly. None of these are enforced, but in future implementations they probably will be. Some known examples are:
+ * commonly used. Some known examples are:
  * <ul>
- *     <li>Using "min" or "max" special segments as a non-trailing segment. This yields in "undefined" behaviour and should be avoided.</li>
+ *     <li>Using "min" or "max" special segments as a non-trailing segment. Comparisons with such strings are "undefined" and should be avoided.</li>
  *     <li>Having a non-number as the first segment of a version. Versions are expected (but not enforced) to start with numbers.</li>
  * </ul>
  */