Add documentation on Artifact, ArtifactCoordinate, Dependency and Dep…

…endencyCoordinate.

Rename ArtifactCoordinate.getVersion() as getVersionConstraint().

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

@@ -23,76 +23,83 @@
 import org.apache.maven.api.annotations.Nonnull;
 
 /**
- * An artifact points to a resource such as a jar file or war application.
+ * Pointer to a resolved resource such as a <abbr>JAR</abbr> file or <abbr>WAE</abbr> application.
+ * {@code Artifact} instances are created when <dfn>resolving</dfn> {@link Artifact} instances.
+ * Resolving is the process that selects a {@linkplain #getVersion() particular version}
+ * and downloads the artifact in the local repository.
+ * The download may be deferred to the first time that the file is needed.
  *
  * @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 ArtifactCoordinate#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 ArtifactCoordinate#getGroupId()
      */
     @Nonnull
     String getGroupId();
 
     /**
-     * The artifactId of the artifact.
+     * {@return the identifier of the artifact}.
      *
-     * @return the artifactId
+     * @see ArtifactCoordinate#getArtifactId()
      */
     @Nonnull
     String getArtifactId();
 
     /**
-     * The version of the artifact.
+     * {@return the version of the artifact}. Contrarily to {@link ArtifactCoordinate},
+     * each {@code Artifact} is associated to a specific version instead of a range of versions.
      *
-     * @return the version
+     * @see ArtifactCoordinate#getVersionConstraint()
      */
     @Nonnull
     Version getVersion();
 
     /**
-     * The base version of the artifact.
-     *
-     * @return the version
+     * {@return the base version of the artifact}.
+     * TODO: this javadoc is not helpful.
      */
     @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 ArtifactCoordinate#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 ArtifactCoordinate#getExtension()
      */
     @Nonnull
     String getExtension();
@@ -106,9 +113,9 @@ default String key() {
     boolean isSnapshot();
 
     /**
-     * Shortcut for {@code session.createArtifactCoordinate(artifact)}
+     * {@return coordinate with the same identifiers as this artifact}.
+     * This is a shortcut for {@code session.createArtifactCoordinate(artifact)}.
      *
-     * @return an {@link ArtifactCoordinate}
      * @see org.apache.maven.api.Session#createArtifactCoordinate(Artifact)
      */
     @Nonnull

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

@@ -23,64 +23,68 @@
 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.
+ * Point to an {@link Artifact} but with the version specified as a range instead of an exact version.
+ * Each {@code ArtifactCoordinate} instance is basically a pointer to a file in the Maven repository,
+ * except that the version may not be defined precisely.
  *
  * @since 4.0.0
  */
 @Experimental
 @Immutable
 public interface ArtifactCoordinate {
-
     /**
-     * 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 range of versions of the artifact}.
      */
     @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,30 +23,45 @@
 import org.apache.maven.api.annotations.Nonnull;
 
 /**
+ * Result of resolving a {@code DependencyCoordinate}.
+ * Resolving is the process that clarifies the obligation (optional or mandatory status),
+ * selects a particular version and downloads the artifact in the local repository.
  *
  * @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 DependencyCoordinate#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 DependencyCoordinate#getScope()
+     */
     @Nonnull
     DependencyScope getScope();
 
+    /**
+     * Returns whether the dependency is optional or mandatory.
+     * Contrarily to {@link DependencyCoordinate}, the obligation of a dependency cannot be unspecified.
+     *
+     * @return {@code true} if the dependency is optional, or {@code false} if mandatory
+     * @see DependencyCoordinate#getOptional()
+     */
     boolean isOptional();
 
     /**
-     * Creates a {@code DependencyCoordinate} based on this {@code Dependency}.
-     *
-     * @return a {@link DependencyCoordinate}
+     * {@return coordinate with the same identifiers as this dependency}.
      */
     @Nonnull
     @Override

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

@@ -26,26 +26,43 @@
 import org.apache.maven.api.annotations.Nullable;
 
 /**
+ * {@code ArtifactCoordinate} completed with information about how the artifact will be used.
+ * Those information include the dependency type (main classes, test classes, <i>etc.</i>),
+ * a scope (compile-time, run-time <i>etc.</i>), and an obligation (whether the dependency
+ * is optional or mandatory). The {@linkplain #getVersionConstraint() version}
+ * and the {@linkplain #getOptional() obligation} may not be defined precisely.
  *
  * @since 4.0.0
  */
 @Experimental
 @Immutable
 public interface DependencyCoordinate extends ArtifactCoordinate {
     /**
-     * The type of the artifact.
-     *
-     * @return the 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>
      */
     @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
+ * Represents at which time the dependency will be used.
+ * If may be, for example, at compile time only, at run time 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}.
  *

api/maven-api-core/src/main/java/org/apache/maven/api/package-info.java

@@ -0,0 +1,47 @@
+/*
+ * 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.
+ */
+
+/**
+ * Core API for Maven plugins.
+ *
+ * <h2>Dependency management</h2>
+ * <p>{@link org.apache.maven.api.ArtifactCoordinate} instances are used to locate artifacts in a repository.
+ * Each instance is basically a pointer to a file in the Maven repository, except that the version may not be
+ * defined precisely.</p>
+ *
+ * <p>{@link org.apache.maven.api.Artifact} instances are the pointed artifacts in the repository.
+ * They are created when <dfn>resolving</dfn> an {@code ArtifactCoordinate}. Resolving is the process
+ * that selects a particular version and downloads the artifact in the local repository.
+ * The download may be deferred to the first time that the file is needed.</p>
+ *
+ * <p>{@link org.apache.maven.api.DependencyCoordinate} instances are used to express a dependency.
+ * They are an {@code ArtifactCoordinate} completed with information about how the artifact will be used:
+ * type, scope and obligation (whether the dependency is optional or mandatory).
+ * The version and the obligation may not be defined precisely.</p>
+ *
+ * <p>{@link org.apache.maven.api.Dependency} instances are the pointed dependencies in the repository.
+ * They are created when <dfn>resolving</dfn> a {@code DependencyCoordinate}.
+ * Resolving is the process that clarifies the obligation (optional or mandatory status),
+ * selects a particular version and downloads the artifact in the local repository.</p>
+ *
+ * <p>{@link org.apache.maven.api.Node} is the main output of the <dfn>dependency collection</dfn> process.
+ * it's the graph of dependencies. The above-cited {@code Dependency} instances are the outputs of the
+ * collection process, part of the graph computed from one or more {@code DependencyCoordinate}s.</p>
+ */
+package org.apache.maven.api;

api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactCoordinateFactoryRequest.java

@@ -100,7 +100,7 @@ static ArtifactCoordinateFactoryRequest build(@Nonnull Session session, @Nonnull
                 .groupId(nonNull(coordinate, "coordinate").getGroupId())
                 .artifactId(coordinate.getArtifactId())
                 .classifier(coordinate.getClassifier())
-                .version(coordinate.getVersion().asString())
+                .version(coordinate.getVersionConstraint().asString())
                 .extension(coordinate.getExtension())
                 .build();
     }

api/maven-api-core/src/main/java/org/apache/maven/api/services/DependencyCoordinateFactoryRequest.java

@@ -74,7 +74,7 @@ static DependencyCoordinateFactoryRequest build(@Nonnull Session session, @Nonnu
                 .session(nonNull(session, "session cannot be null"))
                 .groupId(nonNull(coordinate, "coordinate cannot be null").getGroupId())
                 .artifactId(coordinate.getArtifactId())
-                .version(coordinate.getVersion().asString())
+                .version(coordinate.getVersionConstraint().asString())
                 .classifier(coordinate.getClassifier())
                 .extension(coordinate.getExtension())
                 .build();

maven-api-impl/src/main/java/org/apache/maven/internal/impl/AbstractSession.java

@@ -306,7 +306,7 @@ public org.eclipse.aether.graph.Dependency toDependency(DependencyCoordinate dep
                             dependency.getArtifactId(),
                             dependency.getClassifier(),
                             type.getExtension(),
-                            dependency.getVersion().toString(),
+                            dependency.getVersionConstraint().toString(),
                             Map.of("type", type.id()),
                             (ArtifactType) null),
                     dependency.getScope().id(),
@@ -357,7 +357,7 @@ public org.eclipse.aether.artifact.Artifact toArtifact(ArtifactCoordinate coord)
                 coord.getArtifactId(),
                 coord.getClassifier(),
                 coord.getExtension(),
-                coord.getVersion().toString(),
+                coord.getVersionConstraint().toString(),
                 null,
                 (File) null);
     }