From 748d241076c3fecf25ee90dbf107b477a2bc7254 Mon Sep 17 00:00:00 2001 From: Martin Desruisseaux Date: Tue, 13 Aug 2024 12:11:47 +0200 Subject: [PATCH] Update documentation according comments posted on #1640. --- .../src/main/java/org/apache/maven/api/Artifact.java | 11 ++++++++--- .../org/apache/maven/api/ArtifactCoordinate.java | 5 +++-- .../main/java/org/apache/maven/api/Dependency.java | 12 ++++++++---- .../java/org/apache/maven/api/DependencyScope.java | 4 ++-- .../src/main/java/org/apache/maven/api/Version.java | 4 +++- .../main/java/org/apache/maven/api/package-info.java | 8 ++++++++ 6 files changed, 32 insertions(+), 12 deletions(-) diff --git a/api/maven-api-core/src/main/java/org/apache/maven/api/Artifact.java b/api/maven-api-core/src/main/java/org/apache/maven/api/Artifact.java index 607fddb9be2..41a8f711dc2 100644 --- a/api/maven-api-core/src/main/java/org/apache/maven/api/Artifact.java +++ b/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 JAR file or WAE application. - * {@code Artifact} instances are created when resolving {@link Artifact} instances. + * Each {@code Artifact} instance is basically a pointer to a file in the Maven repository. + * {@code Artifact} instances are created when resolving {@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,6 +73,8 @@ 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() */ @@ -79,8 +82,10 @@ default String key() { 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(); diff --git a/api/maven-api-core/src/main/java/org/apache/maven/api/ArtifactCoordinate.java b/api/maven-api-core/src/main/java/org/apache/maven/api/ArtifactCoordinate.java index eeda74bb147..a7153f79f8d 100644 --- a/api/maven-api-core/src/main/java/org/apache/maven/api/ArtifactCoordinate.java +++ b/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(); diff --git a/api/maven-api-core/src/main/java/org/apache/maven/api/Dependency.java b/api/maven-api-core/src/main/java/org/apache/maven/api/Dependency.java index ffefc2ba4f6..77e9ddaca44 100644 --- a/api/maven-api-core/src/main/java/org/apache/maven/api/Dependency.java +++ b/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 collection process, which builds the graph of dependencies, + * followed by flattening and resolution. + * 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() diff --git a/api/maven-api-core/src/main/java/org/apache/maven/api/DependencyScope.java b/api/maven-api-core/src/main/java/org/apache/maven/api/DependencyScope.java index 78c8c7c03c1..6002baccf91 100644 --- a/api/maven-api-core/src/main/java/org/apache/maven/api/DependencyScope.java +++ b/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}. diff --git a/api/maven-api-core/src/main/java/org/apache/maven/api/Version.java b/api/maven-api-core/src/main/java/org/apache/maven/api/Version.java index ee29cc2b7e6..4521c3e67d9 100644 --- a/api/maven-api-core/src/main/java/org/apache/maven/api/Version.java +++ b/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) diff --git a/api/maven-api-core/src/main/java/org/apache/maven/api/package-info.java b/api/maven-api-core/src/main/java/org/apache/maven/api/package-info.java index b3b630ccc0b..e2bbc498451 100644 --- a/api/maven-api-core/src/main/java/org/apache/maven/api/package-info.java +++ b/api/maven-api-core/src/main/java/org/apache/maven/api/package-info.java @@ -20,6 +20,14 @@ /** * Core API for Maven plugins. * + *

Definitions of terms

+ *

Artifact resolution is the process of {@linkplain org.apache.maven.api.services.VersionResolver + * resolving the version} and then downloading the file.

+ * + *

Dependency resolution 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.

+ * *

Dependency management

*

{@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