Renaming of ArtifactCoordinate.getVersion() + documentation (#1662)

* Rename ArtifactCoordinate.getVersion() as getVersionConstraint().
* Introduce DownloadedArtifact, DownloadedDependency and ProducedArtifact.
* Rename coordinate -> coordinates.
* Add documentation on Artifact, ArtifactCoordinates, Dependency and DependencyCoordinates and other classes.
* Remove `LATEST` and `SNAPSHOT` from documentation since they are deprecated.
* Opportunistic addition of some missing `@Override` annotations.

---------

Co-authored-by: Martin Desruisseaux <martin.desruisseaux@geomatys.com>

api/maven-api-core/src/main/java/org/apache/maven/api/Artifact.java

@@ -23,76 +23,91 @@
 import org.apache.maven.api.annotations.Nonnull;
 
 /**
- * An artifact points to a resource such as a jar file or war application.
+ * A Maven artifact is a file, typically a JAR, that is produced and used by Maven projects.
+ * It is identified by a unique combination of a group ID, artifact ID, version, classifier,
+ * and extension, and it is stored in a repository for dependency management and build purposes.
+ *
+ * <p>Each {@code Artifact} instance is basically an exact pointer to a file in a Maven repository.
+ * {@code Artifact} instances are created when <dfn>resolving</dfn> {@link ArtifactCoordinates} instances.
+ * Resolving is the process that selects a {@linkplain #getVersion() particular version}
+ * and downloads the artifact in the local repository.  This operation returns a {@link DownloadedArtifact}.
+ * </p>
  *
  * @since 4.0.0
  */
 @Experimental
 @Immutable
 public interface Artifact {
-
     /**
-     * Returns a unique identifier for this artifact.
+     * {@return a unique identifier for this artifact}.
      * The identifier is composed of groupId, artifactId, extension, classifier, and version.
      *
-     * @return the unique identifier
+     * @see ArtifactCoordinates#getId()
      */
     @Nonnull
     default String key() {
+        String c = getClassifier();
         return getGroupId()
                 + ':'
                 + getArtifactId()
                 + ':'
                 + getExtension()
-                + (getClassifier().isEmpty() ? "" : ":" + getClassifier())
+                + (c.isEmpty() ? "" : ":" + c)
                 + ':'
                 + getVersion();
     }
 
     /**
-     * The groupId of the artifact.
+     * {@return the group identifier of the artifact}.
      *
-     * @return the groupId
+     * @see ArtifactCoordinates#getGroupId()
      */
     @Nonnull
     String getGroupId();
 
     /**
-     * The artifactId of the artifact.
+     * {@return the identifier of the artifact}.
      *
-     * @return the artifactId
+     * @see ArtifactCoordinates#getArtifactId()
      */
     @Nonnull
     String getArtifactId();
 
     /**
-     * The version of the artifact.
+     * {@return the version of the artifact}. Contrarily to {@link ArtifactCoordinates},
+     * each {@code Artifact} is associated to a specific version instead of a range of versions.
+     * If the {@linkplain #getBaseVersion() base version} contains a meta-version such as {@code SNAPSHOT},
+     * those keywords are replaced by, for example, the actual timestamp.
      *
-     * @return the version
+     * @see ArtifactCoordinates#getVersionConstraint()
      */
     @Nonnull
     Version getVersion();
 
     /**
-     * The base version of the artifact.
-     *
-     * @return the version
+     * {@return the version or meta-version of the artifact}.
+     * A meta-version is a version suffixed with the {@code SNAPSHOT} keyword.
+     * Meta-versions are represented in a base version by their symbols (e.g., {@code SNAPSHOT}),
+     * while they are replaced by, for example, the actual timestamp in the {@linkplain #getVersion() version}.
      */
     @Nonnull
     Version getBaseVersion();
 
     /**
-     * The classifier of the artifact.
+     * Returns the classifier of the artifact.
      *
      * @return the classifier or an empty string if none, never {@code null}
+     * @see ArtifactCoordinates#getClassifier()
      */
     @Nonnull
     String getClassifier();
 
     /**
-     * The file extension of the artifact.
+     * Returns the file extension of the artifact.
+     * The dot separator is <em>not</em> included in the returned string.
      *
-     * @return the extension
+     * @return the file extension or an empty string if none, never {@code null}
+     * @see ArtifactCoordinates#getExtension()
      */
     @Nonnull
     String getExtension();
@@ -106,11 +121,11 @@ default String key() {
     boolean isSnapshot();
 
     /**
-     * Shortcut for {@code session.createArtifactCoordinate(artifact)}
+     * {@return coordinates with the same identifiers as this artifact}.
+     * This is a shortcut for {@code session.createArtifactCoordinates(artifact)}.
      *
-     * @return an {@link ArtifactCoordinate}
-     * @see org.apache.maven.api.Session#createArtifactCoordinate(Artifact)
+     * @see org.apache.maven.api.Session#createArtifactCoordinates(Artifact)
      */
     @Nonnull
-    ArtifactCoordinate toCoordinate();
+    ArtifactCoordinates toCoordinates();
 }

api/maven-api-core/src/main/java/org/apache/maven/api/ArtifactCoordinate.java → api/maven-api-core/src/main/java/org/apache/maven/api/ArtifactCoordinates.java

@@ -23,64 +23,70 @@
 import org.apache.maven.api.annotations.Nonnull;
 
 /**
- * The {@code Coordinate} object is used to point to an {@link Artifact}
- * but the version may be specified as a range instead of an exact version.
+ * Partial identification of an {@link Artifact} in a Maven repository.
+ * Each {@code ArtifactCoordinates} instance is basically a pointer to a file in the Maven repository,
+ * except that the exact version may not be known yet.
  *
  * @since 4.0.0
  */
 @Experimental
 @Immutable
-public interface ArtifactCoordinate {
-
+public interface ArtifactCoordinates {
     /**
-     * The groupId of the artifact.
-     *
-     * @return the groupId
+     * {@return the group identifier of the artifact}.
      */
     @Nonnull
     String getGroupId();
 
     /**
-     * The artifactId of the artifact.
-     *
-     * @return the artifactId
+     * {@return the identifier of the artifact}.
      */
     @Nonnull
     String getArtifactId();
 
     /**
-     * The classifier of the artifact.
+     * Returns the classifier of the artifact.
      *
      * @return the classifier or an empty string if none, never {@code null}
      */
     @Nonnull
     String getClassifier();
 
     /**
-     * The version of the artifact.
-     *
-     * @return the version
+     * {@return the specific version, range of versions or meta-version of the artifact}.
+     * A meta-version is a version suffixed with the {@code SNAPSHOT} keyword.
      */
     @Nonnull
-    VersionConstraint getVersion();
+    VersionConstraint getVersionConstraint();
 
     /**
-     * The extension of the artifact.
+     * Returns the file extension of the artifact.
+     * The dot separator is <em>not</em> included in the returned string.
      *
-     * @return the extension or an empty string if none, never {@code null}
+     * @return the file extension or an empty string if none, never {@code null}
      */
     @Nonnull
     String getExtension();
 
     /**
-     * Unique id identifying this artifact
+     * {@return a unique string representation identifying this artifact}
+     *
+     * The default implementation returns a colon-separated list of group
+     * identifier, artifact identifier, extension, classifier and version.
+     *
+     * @see Artifact#key()
      */
     @Nonnull
     default String getId() {
+        String c = getClassifier();
         return getGroupId()
-                + ":" + getArtifactId()
-                + ":" + getExtension()
-                + (getClassifier().isEmpty() ? "" : ":" + getClassifier())
-                + ":" + getVersion();
+                + ':'
+                + getArtifactId()
+                + ':'
+                + getExtension()
+                + ':'
+                + c
+                + (c.isEmpty() ? "" : ":")
+                + getVersionConstraint();
     }
 }

api/maven-api-core/src/main/java/org/apache/maven/api/Dependency.java

@@ -23,32 +23,51 @@
 import org.apache.maven.api.annotations.Nonnull;
 
 /**
+ * A result of collecting, flattening and resolving {@link DependencyCoordinates}s.
+ * Dependency is the output of the <dfn>collection</dfn> process, which builds the graph of dependencies,
+ * followed by <dfn>flattening</dfn> and <dfn>resolution</dfn>.
+ * The version selection is done for each dependency during the collection phase.
+ * The flatten phase will keep only a single version per ({@code groupId}, {@code artifactId}) pair.
+ * The resolution will actually download the dependencies (or artifacts) that have been computed.
  *
  * @since 4.0.0
  */
 @Experimental
 @Immutable
 public interface Dependency extends Artifact {
-
     /**
-     * The dependency type.
+     * {@return the type of the dependency}. A dependency can be a <abbr>JAR</abbr> file,
+     * a modular-<abbr>JAR</abbr> if it is intended to be placed on the module-path,
+     * a <abbr>JAR</abbr> containing test classes, <i>etc.</i>
      *
-     * @return the dependency type, never {@code null}
+     * @see DependencyCoordinates#getType()
      */
     @Nonnull
     Type getType();
 
+    /**
+     * {@return the time at which the dependency will be used}.
+     * If may be, for example, at compile time only, at run time or at test time.
+     *
+     * @see DependencyCoordinates#getScope()
+     */
     @Nonnull
     DependencyScope getScope();
 
+    /**
+     * Returns whether the dependency is optional or mandatory.
+     * Contrarily to {@link DependencyCoordinates}, the obligation of a {@code Dependency} is always present.
+     * The value is computed during the dependencies collection phase.
+     *
+     * @return {@code true} if the dependency is optional, or {@code false} if mandatory
+     * @see DependencyCoordinates#getOptional()
+     */
     boolean isOptional();
 
     /**
-     * Creates a {@code DependencyCoordinate} based on this {@code Dependency}.
-     *
-     * @return a {@link DependencyCoordinate}
+     * {@return coordinates with the same identifiers as this dependency}
      */
     @Nonnull
     @Override
-    DependencyCoordinate toCoordinate();
+    DependencyCoordinates toCoordinates();
 }

api/maven-api-core/src/main/java/org/apache/maven/api/DependencyCoordinates.java

@@ -0,0 +1,69 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.maven.api;
+
+import java.util.Collection;
+
+import org.apache.maven.api.annotations.Experimental;
+import org.apache.maven.api.annotations.Immutable;
+import org.apache.maven.api.annotations.Nonnull;
+import org.apache.maven.api.annotations.Nullable;
+
+/**
+ * {@code ArtifactCoordinates} completed with information about how the artifact will be used.
+ * This information include the dependency type (main classes, test classes, <i>etc.</i>),
+ * a scope (compile-time, run-time <i>etc.</i>), an obligation (whether the dependency
+ * is optional or mandatory), and possible exclusions for transitive dependencies.
+ * The {@linkplain #getVersionConstraint() version} and the {@linkplain #getOptional() obligation}
+ * may not be defined precisely.
+ *
+ * @since 4.0.0
+ */
+@Experimental
+@Immutable
+public interface DependencyCoordinates extends ArtifactCoordinates {
+    /**
+     * {@return the type of the dependency}. A dependency can be a <abbr>JAR</abbr> file,
+     * a modular-<abbr>JAR</abbr> if it is intended to be placed on the module-path,
+     * a <abbr>JAR</abbr> containing test classes, <i>etc.</i>
+     */
+    @Nonnull
+    Type getType();
+
+    /**
+     * {@return the time at which the dependency will be used}.
+     * If may be, for example, at compile time only, at run time or at test time.
+     */
+    @Nonnull
+    DependencyScope getScope();
+
+    /**
+     * Returns whether the dependency is optional, mandatory or of unspecified obligation.
+     *
+     * @return the obligation, or {@code null} if unspecified
+     */
+    @Nullable
+    Boolean getOptional();
+
+    /**
+     * {@return transitive dependencies to exclude}.
+     */
+    @Nonnull
+    Collection<Exclusion> getExclusions();
+}

api/maven-api-core/src/main/java/org/apache/maven/api/DependencyScope.java

@@ -28,9 +28,9 @@
 import org.apache.maven.api.annotations.Nonnull;
 
 /**
- * Dependency scope.
- * This represents at which time the dependency will be used, for example, at compile time only,
- * at run time or at test time.  For a given dependency, the scope is directly derived from the
+ * Indicates when the dependency will be used.
+ * For example, it may be at compile time only, at runtime, or at test time.
+ * For a given dependency, the scope is directly derived from the
  * {@link org.apache.maven.api.model.Dependency#getScope()} and will be used when using {@link PathScope}
  * and the {@link org.apache.maven.api.services.DependencyResolver}.
  *
@@ -50,7 +50,7 @@ public enum DependencyScope {
 
     /**
      * Undefined. When no scope is explicitly given, UNDEFINED will be used, but its meaning will depend on
-     * whether the DependencyCoordinate is used in dependency management, in which case it means the scope is not
+     * whether the DependencyCoordinates is used in dependency management, in which case it means the scope is not
      * explicitly managed by this managed dependency, or as a real dependency, in which case, the scope
      * will default to {@link #COMPILE}.
      */