This is an automated email from the ASF dual-hosted git repository.
elharo pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven.git
The following commit(s) were added to refs/heads/master by this push:
new 0710deb4fd [MNG-8613] Copy edit dependency javadocs (#2143)
0710deb4fd is described below
commit 0710deb4fd9b132183597dbaed9734eeff621fa1
Author: Elliotte Rusty Harold <elh...@users.noreply.github.com>
AuthorDate: Wed Mar 5 14:29:21 2025 +0000
[MNG-8613] Copy edit dependency javadocs (#2143)
* Copy edit dependency javadocs
---
.../main/java/org/apache/maven/api/Dependency.java | 10 ++---
.../apache/maven/api/DependencyCoordinates.java | 6 +--
.../src/main/java/org/apache/maven/api/Node.java | 4 +-
.../java/org/apache/maven/api/package-info.java | 45 +++++++++++-----------
.../api/services/DependencyResolverResult.java | 10 ++---
5 files changed, 38 insertions(+), 37 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..5a2ad2b9d4 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.
+ * Unlike {@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..cbcc264db6 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 {@code Boolean.TRUE} and {@code Boolean.FALSE} if optional, or
{@code null} if unspecified
*/
@Nullable
Boolean getOptional();
diff --git a/api/maven-api-core/src/main/java/org/apache/maven/api/Node.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/Node.java
index 247cc47983..ee8a4d3796 100644
--- a/api/maven-api-core/src/main/java/org/apache/maven/api/Node.java
+++ b/api/maven-api-core/src/main/java/org/apache/maven/api/Node.java
@@ -100,9 +100,9 @@ public interface Node {
String asString();
/**
- * Obtain a Stream containing this node and all its descendant.
+ * Obtain a Stream containing this node and all its descendants.
*
- * @return a stream containing this node and its descendant
+ * @return a stream containing this node and its descendants
*/
@Nonnull
default Stream<Node> stream() {
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 5f85ff9ad1..7fd2d60b95 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
@@ -38,32 +38,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.
- * 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.
+ * <p>{@link org.apache.maven.api.Artifact} instances represent artifacts in
the repository.
+ * They are created when <dfn>resolving</dfn> an {@code ArtifactCoordinates}
object. Resolving is the process
+ * that selects a particular version and downloads the artifact into the local
repository.
* The {@link org.apache.maven.api.DownloadedArtifact} sub-interface is used
when
- * an artifact has been resolved and {@link
org.apache.maven.api.ProducedArtifact} when
+ * an artifact has been resolved and the {@link
org.apache.maven.api.ProducedArtifact} sub-interface when
* an artifact is being produced by a project.</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).
+ * <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
+ * 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>
*
@@ -76,12 +76,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 a map of ordered lists that can be turned
into classpaths.
+ * During this process 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,
@@ -112,19 +113,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>
*
*/
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/DependencyResolverResult.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/DependencyResolverResult.java
index af53d280e2..456cd6b505 100644
---
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/DependencyResolverResult.java
+++
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/DependencyResolverResult.java
@@ -68,7 +68,7 @@ public interface DependencyResolverResult extends
Result<DependencyResolverReque
List<Node> getNodes();
/**
- * Returns the file paths of all dependencies, regardless on which tool
option those paths should be placed.
+ * Returns the file paths of all dependencies, regardless of which tool
option those paths should be placed on.
* The returned list may contain a mix of Java class path, Java module
path, and other types of path elements.
* This collection has the same content as {@code
getDependencies.values()} except that it does not contain
* null elements.
@@ -79,7 +79,7 @@ public interface DependencyResolverResult extends
Result<DependencyResolverReque
List<Path> getPaths();
/**
- * Returns the file paths of all dependencies, dispatched according the
tool options where to place them.
+ * Returns the file paths of all dependencies and their assignments to
different paths.
* The {@link PathType} keys identify, for example, {@code --class-path}
or {@code --module-path} options.
* In the case of Java tools, the map may also contain {@code
--patch-module} options, which are
* {@linkplain org.apache.maven.api.JavaPathType#patchModule(String)
handled in a special way}.
@@ -88,7 +88,7 @@ public interface DependencyResolverResult extends
Result<DependencyResolverReque
* All types of path are determined together because they are sometime
mutually exclusive.
* For example, an artifact of type {@value org.apache.maven.api.Type#JAR}
can be placed
* either on the class-path or on the module-path. The project needs to
make a choice
- * (possibly using heuristic rules), then to add the dependency in only
one of the options
+ * (possibly using heuristic rules), then add the dependency in only one
of the paths
* identified by {@link PathType}.
*
* @return file paths to place on the different tool options
@@ -97,8 +97,8 @@ public interface DependencyResolverResult extends
Result<DependencyResolverReque
Map<PathType, List<Path>> getDispatchedPaths();
/**
- * {@return all dependencies associated to their paths}
- * Some dependencies may be associated to a null value if there is no path
available.
+ * {@return all dependencies associated with their paths}
+ * Some dependencies may be associated with a null value if there is no
path available.
*/
@Nonnull
Map<Dependency, Path> getDependencies();
