[MRESOLVER-598] Improve Javadoc on version ranges

Point out that the exact syntax of a version depends on the underlying
provider

maven-resolver-api/src/main/java/org/eclipse/aether/RepositorySystem.java

@@ -70,7 +70,7 @@
 public interface RepositorySystem extends Closeable {
 
     /**
-     * Expands a version range to a list of matching versions, in ascending order. For example, resolves "[3.8,4.0)" to
+     * Expands an artifact's version range to a list of matching versions, in ascending order. For example, resolves "[3.8,4.0)" to
      * "3.8", "3.8.1", "3.8.2". Note that the returned list of versions is only dependent on the configured repositories
      * and their contents, the list is not processed by the {@link RepositorySystemSession#getVersionFilter() session's
      * version filter}.
@@ -79,11 +79,12 @@ public interface RepositorySystem extends Closeable {
      * though, the result contains simply the (parsed) input version, regardless of the repositories and their contents.
      *
      * @param session The repository session, must not be {@code null}.
-     * @param request The version range request, must not be {@code null}.
+     * @param request The version range request, must not be {@code null}. It holds the {@link Artifact} whose version range to resolve.
      * @return The version range result, never {@code null}.
      * @throws VersionRangeResolutionException If the requested range could not be parsed. Note that an empty range does
      *                                         not raise an exception.
      * @see #newResolutionRepositories(RepositorySystemSession, List)
+     * @see Artifact#getVersion()
      */
     VersionRangeResult resolveVersionRange(RepositorySystemSession session, VersionRangeRequest request)
             throws VersionRangeResolutionException;
@@ -93,10 +94,11 @@ VersionRangeResult resolveVersionRange(RepositorySystemSession session, VersionR
      * "1.0-20090208.132618-23".
      *
      * @param session The repository session, must not be {@code null}.
-     * @param request The version request, must not be {@code null}.
+     * @param request The version request, must not be {@code null}. It holds the {@link Artifact} whose version to resolve.
      * @return The version result, never {@code null}.
      * @throws VersionResolutionException If the metaversion could not be resolved.
      * @see #newResolutionRepositories(RepositorySystemSession, List)
+     * @see Artifact#getVersion()
      */
     VersionResult resolveVersion(RepositorySystemSession session, VersionRequest request)
             throws VersionResolutionException;

maven-resolver-api/src/main/java/org/eclipse/aether/artifact/Artifact.java

@@ -22,6 +22,8 @@
 import java.nio.file.Path;
 import java.util.Map;
 
+import org.eclipse.aether.RepositorySystemSession;
+
 /**
  * A specific artifact. In a nutshell, an artifact has identifying coordinates and optionally a file that denotes its
  * data. <em>Note:</em> Artifact instances are supposed to be immutable, e.g. any exposed mutator method returns a new
@@ -51,6 +53,8 @@ public interface Artifact {
      * Gets the version of this artifact, for example "1.0-20100529-1213". Note that in case of meta versions like
      * "1.0-SNAPSHOT", the artifact's version depends on the state of the artifact. Artifacts that have been resolved or
      * deployed will usually have the meta version expanded.
+     * This may also return version ranges like "[1.0,2.0)". The exact syntax for (meta) versions and version ranges 
+     * depends on the underlying provider (encapsulated in {@link RepositorySystem}).
      *
      * @return The version, never {@code null}.
      */

maven-resolver-api/src/main/java/org/eclipse/aether/artifact/DefaultArtifact.java

@@ -132,7 +132,7 @@ private static String get(String value, String defaultValue) {
      * @param groupId The group identifier of the artifact, may be {@code null}.
      * @param artifactId The artifact identifier of the artifact, may be {@code null}.
      * @param extension The file extension of the artifact, may be {@code null}.
-     * @param version The version of the artifact, may be {@code null}.
+     * @param version The version (may also be a meta version or version range) of the artifact, may be {@code null}.
      */
     public DefaultArtifact(String groupId, String artifactId, String extension, String version) {
         this(groupId, artifactId, "", extension, version);
@@ -146,7 +146,7 @@ public DefaultArtifact(String groupId, String artifactId, String extension, Stri
      * @param artifactId The artifact identifier of the artifact, may be {@code null}.
      * @param classifier The classifier of the artifact, may be {@code null}.
      * @param extension The file extension of the artifact, may be {@code null}.
-     * @param version The version of the artifact, may be {@code null}.
+     * @param version The version (may also be a meta version or version range) of the artifact, may be {@code null}.
      */
     public DefaultArtifact(String groupId, String artifactId, String classifier, String extension, String version) {
         this(groupId, artifactId, classifier, extension, version, null, (File) null);
@@ -162,7 +162,7 @@ public DefaultArtifact(String groupId, String artifactId, String classifier, Str
      * @param artifactId The artifact identifier of the artifact, may be {@code null}.
      * @param classifier The classifier of the artifact, may be {@code null}.
      * @param extension The file extension of the artifact, may be {@code null}.
-     * @param version The version of the artifact, may be {@code null}.
+     * @param version The version (may also be a meta version or version range) of the artifact, may be {@code null}.
      * @param type The artifact type from which to query classifier, file extension and properties, may be {@code null}.
      */
     public DefaultArtifact(
@@ -181,7 +181,7 @@ public DefaultArtifact(
      * @param artifactId The artifact identifier of the artifact, may be {@code null}.
      * @param classifier The classifier of the artifact, may be {@code null}.
      * @param extension The file extension of the artifact, may be {@code null}.
-     * @param version The version of the artifact, may be {@code null}.
+     * @param version The version (may also be a meta version or version range) of the artifact, may be {@code null}.
      * @param properties The properties of the artifact, may be {@code null} if none.
      * @param type The artifact type from which to query classifier, file extension and properties, may be {@code null}.
      */