This is an automated email from the ASF dual-hosted git repository.
elharo pushed a commit to branch package
in repository https://gitbox.apache.org/repos/asf/maven.git
commit 07ee72120f03887e50d7c91e8ebdf59cc840a6b3
Author: Elliotte Rusty Harold <elh...@ibiblio.org>
AuthorDate: Tue Mar 4 08:30:38 2025 -0500
Copy edit dependency javadocs
---
.../main/java/org/apache/maven/api/Dependency.java | 10 ++---
.../apache/maven/api/DependencyCoordinates.java | 6 +--
.../java/org/apache/maven/api/package-info.java | 48 +++++++++++-----------
3 files changed, 33 insertions(+), 31 deletions(-)
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 4aff60b327..3aaa399828 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,12 +23,12 @@
import org.apache.maven.api.annotations.Nonnull;
/**
- * A result of collecting, flattening and resolving {@link
DependencyCoordinates}s.
+ * 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.
+ * The flatten phase keeps only a single version per ({@code groupId}, {@code
artifactId}) pair.
+ * The resolution phase actually downloads the dependencies (or artifacts)
that have been computed.
*
* @since 4.0.0
*/
@@ -48,7 +48,7 @@ public interface Dependency extends Artifact {
/**
* {@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.
+ * It may be, for example, at compile time only, at run time or at test
time.
*
* @see DependencyCoordinates#getScope()
*/
@@ -57,7 +57,7 @@ public interface Dependency extends Artifact {
/**
* Returns whether the dependency is optional or mandatory.
- * Contrarily to {@link DependencyCoordinates}, the obligation of a {@code
Dependency} is always present.
+ * Contrary 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
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/DependencyCoordinates.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/DependencyCoordinates.java
index ada2f8ed0c..827fce5199 100644
---
a/api/maven-api-core/src/main/java/org/apache/maven/api/DependencyCoordinates.java
+++
b/api/maven-api-core/src/main/java/org/apache/maven/api/DependencyCoordinates.java
@@ -42,14 +42,14 @@ 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>
+ * a <abbr>JAR</abbr> containing test classes, a POM file, <i>etc.</i>
*/
@Nonnull
Type getType();
/**
* {@return the time at which the dependency will be used}
- * It may be, for example, at compile time only, at run time or at test
time.
+ * It may be, for example, at compile time only, at run time, or at test
time.
*/
@Nonnull
DependencyScope getScope();
@@ -57,7 +57,7 @@ public interface DependencyCoordinates extends
ArtifactCoordinates {
/**
* Returns whether the dependency is optional, mandatory, or of
unspecified obligation.
*
- * @return the obligation, or {@code null} if unspecified
+ * @return true if optional, false if mandatory, or {@code null} if
unspecified
*/
@Nullable
Boolean getOptional();
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 8addcd57ca..31eae02df2 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
@@ -23,31 +23,32 @@
* <h3>Dependency management</h3>
*
* <p>{@link org.apache.maven.api.ArtifactCoordinates} 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>
+ * Each instance identifies an artifact or version range of artifacts in the
Maven repository system.</p>
*
- * <p>{@link org.apache.maven.api.Artifact} instances are the pointed
artifacts in the repository.
+ * <p>{@link org.apache.maven.api.Artifact} instances represent artifacts in
the repository.
* They are created when <dfn>resolving</dfn> an {@code ArtifactCoordinates}.
Resolving is the process
- * that selects a particular version and downloads the artifact in the local
repository.
- * There are two sub-interfaces, {@link
org.apache.maven.api.DownloadedArtifact} which is used when
- * an artifact has been resolved</p>
- *
- * <p>{@link org.apache.maven.api.DependencyCoordinates} instances are used to
express a dependency.
- * They are a {@code ArtifactCoordinates} completed with information about how
the artifact will be used:
- * type, scope and obligation (whether the dependency is optional or
mandatory).
+ * that selects a particular version and downloads the artifact to the local
repository.
+ * The sub-interface {@link org.apache.maven.api.DownloadedArtifact}
represents an artifact
+ * that has been downloaded to and installed in the local repository.</p>
+ *
+ * <p>{@link org.apache.maven.api.DependencyCoordinates} instances represent a
dependency element in a POM.
+ * A {@code DependencyCoordinates} extends {@code ArtifactCoordinates} with
additional information about how
+ * A {@code DependencyCoordinates} extends {@code ArtifactCoordinates} with
additional 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.
+ * <p>{@link org.apache.maven.api.Dependency} instances represent artifacts in
the repository
+ * that are dependencies of the project.
* They are created when <dfn>resolving</dfn> a {@code DependencyCoordinates}.
- * 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>
+ * Resolving is the process that clarifies the obligation (optional or
mandatory),
+ * selects a particular version, and downloads the artifact into 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
+ * It's a node in the dependency graph and contains a {@code Dependency}
instance. The {@code Dependency} instances are the outputs of the
* collection process, part of the graph computed from one or more {@code
DependencyCoordinates}.</p>
*
* <p>{@link org.apache.maven.api.DependencyScope} defines when/how a given
dependency will be used by the
- * project. This includes compile-time only, runtime, test time and various
other combinations.</p>
+ * project. This includes compile-time only, runtime, test time, and various
other combinations.</p>
*
* <h3>Resolution</h3>
*
@@ -60,12 +61,13 @@
* <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 collection</dfn> builds a graph of {@link
org.apache.maven.api.Node} objects representing
+ * <p><dfn>Dependency collection</dfn> builds a graph of {@link
org.apache.maven.api.Node} objects containing
* all the dependencies.</p>
*
- * <p>The <dfn>Dependency graph flattening</dfn> process in Maven involves
reducing a complex,
- * multi-level dependency graph to a simpler list where only the most relevant
version of each artifact
- * (based on groupId and artifactId) is retained, resolving conflicts and
eliminating duplicates to ensure
+ * <p>The <dfn>Dependency graph flattening</dfn> process in Maven reduces a
complex,
+ * multi-level dependency graph to an ordered list that can be turned into a
classpath.
+ * During this process where only the most relevant version of each artifact
+ * (based on group ID and artifact ID) is retained, resolving conflicts and
eliminating duplicates to ensure
* that each dependency is included only once in the final build.</p>
*
* <p><dfn>Dependency resolution</dfn> is the process of collecting
dependencies, flattening the result graph,
@@ -96,19 +98,19 @@
* from a Project Object Model (POM).</p>
*
* <p><dfn>Project Object Model</dfn> or <dfn>POM</dfn> refers to the
information describing
- * all the information needed to build or consume a project. Those are
usually loaded from
+ * all the information needed to build or consume a project. Those are usually
loaded from
* a file named {@code pom.xml} and loaded into a {@link
org.apache.maven.api.model.Model Model}
* instances.</p>
*
* <p><dfn>Project aggregation</dfn> allows building several projects
together. This is only
* for projects that are built, hence available on the file system. One
project,
- * called the <dfn>aggregator project</dfn> will list one or more
<dfn>modules</dfn>
- * which are relative pointers on the file system to other projects. This is
done using
+ * called the <dfn>aggregator project</dfn> lists one or more
<dfn>modules</dfn>
+ * which are relative pointers on the file system to other projects. This is
done using
* the {@code /project/modules/module} elements of the POM in the aggregator
project.
* Note that the aggregator project is required to have a {@code pom}
packaging.</p>
*
* <p><dfn>Project inheritance</dfn> defines a parent-child relationship
between projects.
- * The <dfn>child project</dfn> will inherit all the information from the
<dfn>parent project</dfn>
+ * The <dfn>child project</dfn> inherits all the information from the
<dfn>parent project</dfn>
* POM.</p>
*
*/
