Update documentation according comments posted on apache#1640.

Author: desruisseaux

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

@@ -24,7 +24,8 @@
 
 /**
  * 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.
+ * Each {@code Artifact} instance is basically a pointer to a file in the Maven repository.
+ * {@code Artifact} instances are created when <dfn>resolving</dfn> {@link ArtifactCoordinate} 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.
@@ -72,15 +73,19 @@ default String key() {
     /**
      * {@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.
+     * If the {@linkplain #getBaseVersion() base version} contains a meta-version such as {@code LATEST},
+     * {@code RELEASE} or {@code SNAPSHOT}, those keywords are replaced by, for example, the actual timestamp.
      *
      * @see ArtifactCoordinate#getVersionConstraint()
      */
     @Nonnull
     Version getVersion();
 
     /**
-     * {@return the base version of the artifact}.
-     * TODO: this javadoc is not helpful.
+     * {@return the version or meta-version of the artifact}.
+     * A meta-version is a version suffixed with {@code LATEST}, {@code RELEASE} or {@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();

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

@@ -23,7 +23,7 @@
 import org.apache.maven.api.annotations.Nonnull;
 
 /**
- * Point to an {@link Artifact} but with the version specified as a range instead of an exact version.
+ * Identification of an ensemble of {@code Artifact}s in a range of versions.
  * Each {@code ArtifactCoordinate} instance is basically a pointer to a file in the Maven repository,
  * except that the version may not be defined precisely.
  *
@@ -53,7 +53,8 @@ public interface ArtifactCoordinate {
     String getClassifier();
 
     /**
-     * {@return the range of versions of the artifact}.
+     * {@return the specific version, range of versions or meta-version of the artifact}.
+     * A meta-version is a version suffixed with {@code LATEST}, {@code RELEASE} or {@code SNAPSHOT} keyword.
      */
     @Nonnull
     VersionConstraint getVersionConstraint();

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

@@ -23,9 +23,12 @@
 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.
+ * A result of collecting, flattening and resolving {@code DependencyCoordinate}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
  */
@@ -53,7 +56,8 @@ public interface Dependency extends Artifact {
 
     /**
      * Returns whether the dependency is optional or mandatory.
-     * Contrarily to {@link DependencyCoordinate}, the obligation of a dependency cannot be unspecified.
+     * Contrarily to {@link DependencyCoordinate}, 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 DependencyCoordinate#getOptional()

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

@@ -28,8 +28,8 @@
 import org.apache.maven.api.annotations.Nonnull;
 
 /**
- * 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.
+ * 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}.

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

@@ -22,7 +22,9 @@
 import org.apache.maven.api.annotations.Nonnull;
 
 /**
- * A version usually parsed using the {@link org.apache.maven.api.services.VersionParser} service.
+ * A version or meta-version of an artifact or a dependency.
+ * A meta-version is a version suffixed with {@code LATEST}, {@code RELEASE} or {@code SNAPSHOT} keyword.
+ * Version is usually parsed using the {@link org.apache.maven.api.services.VersionParser} service.
  *
  * @since 4.0.0
  * @see org.apache.maven.api.services.VersionParser#parseVersion(String)

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

@@ -20,6 +20,14 @@
 /**
  * Core API for Maven plugins.
  *
+ * <h2>Definitions of terms</h2>
+ * <p><dfn>Artifact resolution</dfn> is the process of {@linkplain org.apache.maven.api.services.VersionResolver
+ * resolving the version} and then downloading the file.</p>
+ *
+ * <p><dfn>Dependency resolution</dfn> is the process of collecting dependencies, flattening the graph,
+ * and then downloading the file. The flattening phase removes branches of the graph so that one artifact
+ * per ({@code groupId}, {@code artifactId}) pair is present.</p>
+ *
  * <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