docs

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

@@ -18,7 +18,7 @@
  * under the License.
  */
 /**
- * Ready-to-use version scheme for parsing/comparing versions and utility classes.
+ * 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).
@@ -28,12 +28,13 @@
  * <p>
  * Below is the <em>Generic Version Spec</em> described:
  * <p>
- * Version string is parsed into version according to these rules below:
+ * Version string is parsed into version according to these rules:
  * <ul>
  *     <li>The version string is parsed into segments, from left to right.</li>
- *     <li>Segments are explicitly delimited by single {@code "." (dot)}, {@code "-" (hyphen)} or {@code "_" (underscore)} character.</li>
- *     <li>Segments are implicitly delimited by transition between digits and non-digits.</li>
- *     <li>Segments are classified as numeric, string, qualifiers (special case of string) and min/max.</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>Qualifier segments (strings listed below) and their sort order (ascending) are:
@@ -48,7 +49,7 @@
  *         </ul>
  *     </li>
  *     <li>String segments are sorted lexicographically and case-insensitively per ROOT locale, ascending.</li>
- *     <li>There are two special segments, {@code "min"} and {@code "max"}, they represent absolute minimum and absolute maximum in comparisons. They can be used only as trailing segment.</li>
+ *     <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>
@@ -57,11 +58,11 @@
  *     <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 (nor cover) many corner cases, that we believe are "atypical" or not
+ * 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:
  * <ul>
- *     <li>Using "min" or "max" special segments as non-trailing segment. This yields in "undefined" behaviour and should be avoided.</li>
- *     <li>Having non-number as first segment of version. Versions are expected (but not enforced) to start with numbers.</li>
+ *     <li>Using "min" or "max" special segments as a non-trailing segment. This yields in "undefined" behaviour 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>
  *
  */