Grammar and typo fixes in javadoc and other comments (#2222)

* A few grammar fixes in javadoc

Author: elharo

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

@@ -203,7 +203,7 @@ public String id() {
     /**
      * Returns the identification of this path in the {@code javax.tool} API.
      * The value may be an instance of {@link StandardLocation} or {@link DocumentationTool.Location},
-     * depending which tool will use this location.
+     * depending on which tool will use this location.
      *
      * @return the {@code javax.tool} enumeration value corresponding to this {@code JavaPathType}
      */

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

@@ -73,7 +73,7 @@ public interface Lifecycle extends ExtensibleEnum {
 
     /**
      * Collection of main phases for this lifecycle used with the Maven 3 builders.
-     * Those builders does not operate on a graph, but on the list and expect a slightly
+     * Those builders do not operate on a graph, but on the list and expect a slightly
      * different ordering (mainly unit test being executed before packaging).
      *
      * @return the collection of phases in Maven 3 compatible ordering

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

@@ -45,10 +45,10 @@ public interface ArtifactInstaller extends Service {
     /**
      * @param session the repository session
      * @param artifact the {@link ProducedArtifact} to install
-     * @throws ArtifactInstallerException In case of an error which can be the a given artifact cannot be found or the
-     *             installation has failed.
-     * @throws IllegalArgumentException in case of parameter {@code session} is {@code null} or
-     *          {@code artifact} is {@code null}.
+     * @throws ArtifactInstallerException in case of an error which can be a given artifact cannot be found or the
+     *             installation has failed
+     * @throws IllegalArgumentException if a parameter {@code session} is {@code null} or
+     *          {@code artifact} is {@code null}
      */
     default void install(Session session, ProducedArtifact artifact) {
         install(session, Collections.singletonList(artifact));
@@ -57,9 +57,9 @@ default void install(Session session, ProducedArtifact artifact) {
     /**
      * @param session the repository session
      * @param artifacts Collection of {@link ProducedArtifact MavenArtifacts}
-     * @throws ArtifactInstallerException In case of an error which can be the a given artifact cannot be found or the
-     *             installation has failed.
-     * @throws IllegalArgumentException in case of parameter {@code request} is {@code null} or parameter
+     * @throws ArtifactInstallerException if the given artifact cannot be found or the
+     *             installation has failed
+     * @throws IllegalArgumentException if {@code request} is {@code null} or parameter
      *             {@code localRepository} is {@code null} or {@code localRepository} is not a directory
      *             or parameter {@code mavenArtifacts} is {@code null} or
      *             {@code mavenArtifacts.isEmpty()} is {@code true}.

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

@@ -27,7 +27,7 @@
 import org.apache.maven.api.settings.Settings;
 
 /**
- * Builds the effective settings from a user settings file and/or a installation settings file.
+ * Builds the effective settings from a user settings file and/or an installation settings file.
  *
  * @since 4.0.0
  */

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

@@ -103,7 +103,7 @@ default T fromXmlString(@Nonnull String xml) throws XmlReaderException {
     }
 
     /**
-     * Simply converts the given content to an xml string.
+     * Converts the given content to an XML string.
      *
      * @param content the object to convert
      * @return the xml string representation

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

@@ -22,7 +22,7 @@
 import org.apache.maven.api.services.MavenException;
 
 /**
- * An exception thrown during the reading of an xml file.
+ * An exception thrown while reading an XML file.
  *
  * @since 4.0.0
  */

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

@@ -22,7 +22,7 @@
 import org.apache.maven.api.services.MavenException;
 
 /**
- * An exception thrown during the writing of an xml file.
+ * An exception thrown while writing an XML file.
  *
  * @since 4.0.0
  */

compat/maven-compat/src/main/java/org/apache/maven/artifact/resolver/ArtifactCollector.java

@@ -27,7 +27,7 @@
 import org.apache.maven.artifact.resolver.filter.ArtifactFilter;
 
 /**
- * Artifact collector - takes a set of original artifacts and resolves all of the best versions to use
+ * Artifact collector - takes a set of original artifacts and resolves the best versions to use
  * along with their metadata. No artifacts are downloaded.
  */
 @Deprecated

compat/maven-compat/src/main/java/org/apache/maven/artifact/resolver/DefaultArtifactCollector.java

@@ -22,7 +22,7 @@
 import javax.inject.Singleton;
 
 /**
- * Artifact collector - takes a set of original artifacts and resolves all of the best versions to use
+ * Artifact collector - takes a set of original artifacts and resolves the best versions to use
  * along with their metadata. No artifacts are downloaded.
  */
 @Deprecated

compat/maven-compat/src/main/java/org/apache/maven/repository/legacy/DefaultWagonManager.java

@@ -602,7 +602,7 @@ private void handleChecksumFailure(String checksumPolicy, String message, Throwa
             // warn if it is set to anything other than ignore
             logger.warn("*** CHECKSUM FAILED - " + message + " - IGNORING");
         }
-        // otherwise it is ignore
+        // otherwise it is ignored
     }
 
     private void verifyChecksum(

compat/maven-compat/src/main/java/org/apache/maven/repository/legacy/resolver/LegacyArtifactCollector.java

@@ -32,9 +32,8 @@
 import org.apache.maven.repository.legacy.resolver.conflict.ConflictResolver;
 
 /**
- * Artifact collector - takes a set of original artifacts and resolves all of the best versions to use
+ * Artifact collector - takes a set of original artifacts and resolves the best versions to use
  * along with their metadata. No artifacts are downloaded.
- *
  */
 @Deprecated
 @SuppressWarnings("checkstyle:parameternumber")

compat/maven-compat/src/main/java/org/apache/maven/repository/metadata/DefaultClasspathTransformation.java

@@ -93,8 +93,7 @@ protected ClasspathGraphVisitor(MetadataGraph cleanGraph, ClasspathContainer cpc
         }
 
         // -----------------------------------------------------------------------
-        protected void visit(MetadataGraphVertex node) // , String version, String artifactUri )
-                {
+        protected void visit(MetadataGraphVertex node) {
             ArtifactMetadata md = node.getMd();
             if (visited.contains(node)) {
                 return;

compat/maven-compat/src/main/java/org/apache/maven/toolchain/java/JavaToolchainFactory.java

@@ -97,7 +97,7 @@ public ToolchainPrivate createToolchain(ToolchainModel model) throws Misconfigur
 
     public ToolchainPrivate createDefaultToolchain() {
         // not sure it's necessary to provide a default toolchain here.
-        // only version can be eventually supplied, and
+        // only version can be eventually supplied.
         return null;
     }
 

compat/maven-embedder/src/main/java/org/fusesource/jansi/Ansi.java

@@ -84,7 +84,7 @@ public int bgBright() {
     }
 
     /**
-     * Display attributes, also know as
+     * Display attributes, also known as
      * <a href="https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_(Select_Graphic_Rendition)_parameters">SGR
      * (Select Graphic Rendition) parameters</a>.
      */

compat/maven-model-builder/src/main/java/org/apache/maven/model/building/DefaultModelProcessor.java

@@ -41,12 +41,12 @@
  * made this component available under all its interfaces then it could end up being injected
  * into itself leading to a stack overflow.
  *
- * A side-effect of using @Typed is that it translates to explicit bindings in the container.
+ * A side effect of using @Typed is that it translates to explicit bindings in the container.
  * So instead of binding the component under a 'wildcard' key it is now bound with an explicit
- * key. Since this is a default component this will be a plain binding of ModelProcessor to
- * this implementation type, ie. no hint/name.
+ * key. Since this is a default component, this will be a plain binding of ModelProcessor to
+ * this implementation type; that is no hint/name.
  *
- * This leads to a second side-effect in that any @Inject request for just ModelProcessor in
+ * This leads to a second side effect in that any @Inject request for just ModelProcessor in
  * the same injector is immediately matched to this explicit binding, which means extensions
  * cannot override this binding. This is because the lookup is always short-circuited in this
  * specific situation (plain @Inject request, and plain explicit binding for the same type.)

compat/maven-model-builder/src/main/java/org/apache/maven/model/building/ModelBuildingRequest.java

@@ -104,7 +104,7 @@ public interface ModelBuildingRequest {
     /**
      * Sets the POM file of the project to build. Note that providing the path to a POM file via this method will make
      * the model builder operate in project mode. This mode is meant for effective models that are employed during the
-     * build process of a local project. Hence the effective model will support the notion of a project directory. To
+     * build process of a local project. Hence, the effective model will support the notion of a project directory. To
      * build the model for a POM from the repository, use {@link #setModelSource(ModelSource)} in combination with a
      * {@link FileModelSource} instead.
      *
@@ -154,7 +154,7 @@ public interface ModelBuildingRequest {
      * builder will only produce an interim result which may be used to analyze inter-model dependencies before the
      * final invocation of the model builder is performed.
      *
-     * @return {@code true} if two-phase building is enabled, {@code false} if the model should be build in a single
+     * @return {@code true} if two-phase building is enabled, {@code false} if the model should be built in a single
      *         step.
      */
     boolean isTwoPhaseBuilding();
@@ -164,7 +164,7 @@ public interface ModelBuildingRequest {
      * interim result which may be used to analyze inter-model dependencies before the final invocation of the model
      * builder is performed.
      *
-     * @param twoPhaseBuilding {@code true} to enable two-phase building, {@code false} if the model should be build in
+     * @param twoPhaseBuilding {@code true} to enable two-phase building, {@code false} if the model should be built in
      *            a single step.
      * @return This request, never {@code null}.
      */

compat/maven-model-builder/src/main/java/org/apache/maven/model/building/ModelCache.java

@@ -22,7 +22,7 @@
  * Caches auxiliary data used during model building like already processed raw/effective models. The data in the cache
  * is meant for exclusive consumption by the model builder and is opaque to the cache implementation. The cache key is
  * formed by a combination of group id, artifact id, version and tag. The first three components generally refer to the
- * identify of a model. The tag allows for further classification of the associated data on the sole discretion of the
+ * identity of a model. The tag allows for further classification of the associated data on the sole discretion of the
  * model builder.
  *
  * @deprecated use {@code org.apache.maven.api.services.ModelBuilder} instead

compat/maven-model-builder/src/main/java/org/apache/maven/model/interpolation/AbstractStringBasedModelInterpolator.java

@@ -158,7 +158,7 @@ public Object getValue(String expression) {
 
         valueSources.add(new MapBasedValueSource(config.getUserProperties()));
 
-        // Overwrite existing values in model properties. Otherwise it's not possible
+        // Overwrite existing values in model properties. Otherwise, it's not possible
         // to define them via command line e.g.: mvn -Drevision=6.5.7 ...
         versionProcessor.overwriteModelProperties(modelProperties, config);
         valueSources.add(new MapBasedValueSource(modelProperties));

compat/maven-model-builder/src/main/java/org/apache/maven/model/interpolation/reflection/ClassMap.java

@@ -127,9 +127,9 @@ private void populateMethodCache() {
             Method publicMethod = getPublicMethod(method);
 
             // it is entirely possible that there is no public method for
-            // the methods of this class (i.e. in the facade, a method
+            // the methods of this class; i.e. in the facade, a method
             // that isn't on any of the interfaces or superclass
-            // in which case, ignore it.  Otherwise, map and cache
+            // in which case, ignore it. Otherwise, map and cache.
             if (publicMethod != null) {
                 methodMap.add(publicMethod);
                 methodCache.put(makeMethodKey(publicMethod), publicMethod);

compat/maven-model-builder/src/main/java/org/apache/maven/model/io/ModelParseException.java

@@ -21,7 +21,7 @@
 import java.io.IOException;
 
 /**
- * Signals a failure to parse the POM due to invalid syntax (e.g. non well formed XML or unknown elements).
+ * Signals a failure to parse the POM due to invalid syntax (e.g. non well-formed XML or unknown elements).
  *
  * @deprecated use {@code org.apache.maven.api.services.xml.ModelXmlFactory} instead
  */

compat/maven-model-builder/src/main/java/org/apache/maven/model/locator/ModelLocator.java

@@ -30,7 +30,7 @@ public interface ModelLocator {
 
     /**
      * Locates the POM file within the specified project directory. In case the given project directory does not exist
-     * or does not contain a POM file, the return value indicates the expected path to the POM file. Sub directories of
+     * or does not contain a POM file, the return value indicates the expected path to the POM file. Subdirectories of
      * the project directory will not be considered when locating the POM file. The return value will be an absolute
      * path if the project directory is given as an absolute path.
      *

compat/maven-model-builder/src/main/java/org/apache/maven/model/resolution/ModelResolver.java

@@ -97,13 +97,13 @@ public interface ModelResolver {
     /**
      * Adds a repository to use for subsequent resolution requests. The order in which repositories are added matters,
      * repositories that were added first should also be searched first. When multiple repositories with the same
-     * identifier are added, then the value of the replace argument is determines the behaviour.
+     * identifier are added, then the value of the replace argument determines the behaviour.
      *
-     * If replace is false than any existing repository with the same Id will remain in use. If replace
-     * is true the new repository replaces the original.
+     * If replace is false, then any existing repository with the same ID will remain in use. If replace
+     * is true, the new repository replaces the original.
      *
-     * @param repository The repository to add to the internal search chain, must not be {@code null}.
-     * @throws InvalidRepositoryException If the repository could not be added (e.g. due to invalid URL or layout).
+     * @param repository the repository to add to the internal search chain, must not be {@code null}
+     * @throws InvalidRepositoryException if the repository could not be added (e.g. due to invalid URL or layout)
      */
     void addRepository(Repository repository, boolean replace) throws InvalidRepositoryException;
 

compat/maven-plugin-api/src/main/java/org/apache/maven/plugin/AbstractMojo.java

@@ -154,7 +154,7 @@ public void setLog(Log log) {
 
     /**
      * <p>
-     * Returns the logger that has been injected into this mojo. If no logger has been setup yet, a
+     * Returns the logger that has been injected into this mojo. If no logger has been set up yet, a
      * <code>SystemStreamLog</code> logger will be created and returned.
      * </p>
      * <strong>Note:</strong>

compat/maven-settings-builder/src/main/java/org/apache/maven/settings/building/SettingsBuildingException.java

@@ -24,7 +24,7 @@
 import java.util.List;
 
 /**
- * Signals one ore more errors during settings building. The settings builder tries to collect as many problems as
+ * Signals one or more errors during settings building. The settings builder tries to collect as many problems as
  * possible before eventually failing to provide callers with rich error information. Use {@link #getProblems()} to
  * query the details of the failure.
  *

compat/maven-settings-builder/src/main/java/org/apache/maven/settings/io/SettingsParseException.java

@@ -21,7 +21,7 @@
 import java.io.IOException;
 
 /**
- * Signals a failure to parse the settings due to invalid syntax (e.g. non well formed XML or unknown elements).
+ * Signals a failure to parse the settings due to invalid syntax (e.g. non well-formed XML or unknown elements).
  *
  * @deprecated since 4.0.0, use {@link org.apache.maven.api.services.xml.SettingsXmlFactory} instead
  */

compat/maven-settings/src/main/java/org/apache/maven/settings/io/xpp3/SettingsXpp3Reader.java

@@ -64,14 +64,6 @@ public void setAddDefaultEntities(boolean addDefaultEntities) {
         delegate.setAddDefaultEntities(addDefaultEntities);
     }
 
-    /**
-     * @param reader a reader object.
-     * @param strict a strict object.
-     * @throws IOException IOException if any.
-     * @throws XmlPullParserException XmlPullParserException if
-     * any.
-     * @return Settings
-     */
     public Settings read(Reader reader, boolean strict) throws IOException, XmlPullParserException {
         try {
             return new Settings(delegate.read(reader, strict, null));
@@ -80,13 +72,6 @@ public Settings read(Reader reader, boolean strict) throws IOException, XmlPullP
         }
     }
 
-    /**
-     * @param reader a reader object.
-     * @throws IOException IOException if any.
-     * @throws XmlPullParserException XmlPullParserException if
-     * any.
-     * @return Model
-     */
     public Settings read(Reader reader) throws IOException, XmlPullParserException {
         try {
             return new Settings(delegate.read(reader));
@@ -95,16 +80,6 @@ public Settings read(Reader reader) throws IOException, XmlPullParserException {
         }
     }
 
-    /**
-     * Method read.
-     *
-     * @param in a in object.
-     * @param strict a strict object.
-     * @throws IOException IOException if any.
-     * @throws XmlPullParserException XmlPullParserException if
-     * any.
-     * @return Settings
-     */
     public Settings read(InputStream in, boolean strict) throws IOException, XmlPullParserException {
         try {
             return new Settings(delegate.read(in, strict, null));
@@ -113,15 +88,6 @@ public Settings read(InputStream in, boolean strict) throws IOException, XmlPull
         }
     }
 
-    /**
-     * Method read.
-     *
-     * @param in a in object.
-     * @throws IOException IOException if any.
-     * @throws XmlPullParserException XmlPullParserException if
-     * any.
-     * @return Settings
-     */
     public Settings read(InputStream in) throws IOException, XmlPullParserException {
         try {
             return new Settings(delegate.read(in));
@@ -130,16 +96,6 @@ public Settings read(InputStream in) throws IOException, XmlPullParserException
         }
     }
 
-    /**
-     * Method read.
-     *
-     * @param parser a parser object.
-     * @param strict a strict object.
-     * @throws IOException IOException if any.
-     * @throws XmlPullParserException XmlPullParserException if
-     * any.
-     * @return Settings
-     */
     public Settings read(XMLStreamReader parser, boolean strict) throws IOException, XmlPullParserException {
         try {
             return new Settings(delegate.read(parser, strict, null));

compat/maven-toolchain-builder/src/main/java/org/apache/maven/toolchain/io/ToolchainsParseException.java

@@ -21,7 +21,7 @@
 import java.io.IOException;
 
 /**
- * Signals a failure to parse the toolchains due to invalid syntax (e.g. non well formed XML or unknown elements).
+ * Signals a failure to parse the toolchains due to invalid syntax (e.g. non well-formed XML or unknown elements).
  *
  * @since 3.3.0
  */

impl/maven-core/src/main/java/org/apache/maven/DefaultMaven.java

@@ -276,9 +276,8 @@ private MavenExecutionResult doExecute(
         // because the participant is free to change the dependencies of a project which can potentially change the
         // topological order of the projects, and therefore can potentially change the build order.
         //
-        // Note that participants may affect the topological order of the projects but it is
+        // Note that participants may affect the topological order of the projects, but it is
         // not expected that a participant will add or remove projects from the session.
-        //
 
         graphResult = buildGraph(session);
 

impl/maven-core/src/main/java/org/apache/maven/artifact/factory/DefaultArtifactFactory.java

@@ -162,7 +162,7 @@ private Artifact createArtifact(
         } else if (Artifact.SCOPE_TEST.equals(scope) || Artifact.SCOPE_PROVIDED.equals(scope)) {
             return null;
         } else if (Artifact.SCOPE_COMPILE.equals(scope) && Artifact.SCOPE_COMPILE.equals(inheritedScope)) {
-            // added to retain compile artifactScope. Remove if you want compile inherited as runtime
+            // added to retain compile artifactScope. Remove if you want to compile inherited as runtime
             desiredScope = Artifact.SCOPE_COMPILE;
         }