Add quotes in the command-line arguments formatted by JavaPathType (apache#2505)

This commit contains also opportunistic documentation fixes.

Author: desruisseaux

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

@@ -39,7 +39,7 @@
 @Immutable
 public interface Artifact {
     /**
-     * {@return a unique identifier for this artifact}
+     * {@return a unique identifier for this artifact}.
      * The identifier is composed of groupId, artifactId, extension, classifier, and version.
      *
      * @see ArtifactCoordinates#getId()
@@ -58,23 +58,23 @@ default String key() {
     }
 
     /**
-     * {@return the group identifier of the artifact}
+     * {@return the group identifier of the artifact}.
      *
      * @see ArtifactCoordinates#getGroupId()
      */
     @Nonnull
     String getGroupId();
 
     /**
-     * {@return the identifier of the artifact}
+     * {@return the identifier of the artifact}.
      *
      * @see ArtifactCoordinates#getArtifactId()
      */
     @Nonnull
     String getArtifactId();
 
     /**
-     * {@return the version of the artifact}
+     * {@return the version of the artifact}.
      * Contrarily to {@link ArtifactCoordinates},
      * 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 SNAPSHOT},
@@ -86,7 +86,7 @@ default String key() {
     Version getVersion();
 
     /**
-     * {@return the version or meta-version of the artifact}
+     * {@return the version or meta-version of the artifact}.
      * A meta-version is a version suffixed with the {@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}.
@@ -122,7 +122,7 @@ default String key() {
     boolean isSnapshot();
 
     /**
-     * {@return coordinates with the same identifiers as this artifact}
+     * {@return coordinates with the same identifiers as this artifact}.
      * This is a shortcut for {@code session.createArtifactCoordinates(artifact)}.
      *
      * @see org.apache.maven.api.Session#createArtifactCoordinates(Artifact)

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

@@ -33,13 +33,13 @@
 @Immutable
 public interface ArtifactCoordinates {
     /**
-     * {@return the group identifier of the artifact}
+     * {@return the group identifier of the artifact}.
      */
     @Nonnull
     String getGroupId();
 
     /**
-     * {@return the identifier of the artifact}
+     * {@return the identifier of the artifact}.
      */
     @Nonnull
     String getArtifactId();
@@ -53,7 +53,7 @@ public interface ArtifactCoordinates {
     String getClassifier();
 
     /**
-     * {@return the specific version, range of versions or meta-version of the artifact}
+     * {@return the specific version, range of versions, or meta-version of the artifact}.
      * A meta-version is a version suffixed with the {@code SNAPSHOT} keyword.
      */
     @Nonnull
@@ -69,7 +69,7 @@ public interface ArtifactCoordinates {
     String getExtension();
 
     /**
-     * {@return a unique string representation identifying this artifact}
+     * {@return a unique string identifying this artifact}.
      *
      * The default implementation returns a colon-separated list of group
      * identifier, artifact identifier, extension, classifier and version.

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

@@ -36,7 +36,7 @@
 @Immutable
 public interface Dependency extends Artifact {
     /**
-     * {@return the type of the dependency}
+     * {@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>
@@ -47,7 +47,7 @@ public interface Dependency extends Artifact {
     Type getType();
 
     /**
-     * {@return the time at which the dependency will be used}
+     * {@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.
      *
      * @see DependencyCoordinates#getScope()
@@ -66,7 +66,7 @@ public interface Dependency extends Artifact {
     boolean isOptional();
 
     /**
-     * {@return coordinates with the same identifiers as this dependency}
+     * {@return coordinates with the same identifiers as this dependency}.
      */
     @Nonnull
     @Override

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

@@ -33,7 +33,7 @@
 public interface DownloadedArtifact extends Artifact {
 
     /**
-     * {@return the actual file that has been downloaded in the file system}
+     * {@return the a path to the file that has been downloaded to the file system}.
      */
     Path getPath();
 }

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

@@ -263,8 +263,8 @@ final String[] format(String moduleName, Iterable<? extends Path> paths) {
         if (option == null) {
             throw new IllegalStateException("No option is associated to this path type.");
         }
-        String prefix = (moduleName == null) ? "" : (moduleName + '=');
-        StringJoiner joiner = new StringJoiner(File.pathSeparator, prefix, "");
+        String prefix = (moduleName == null) ? "\"" : (moduleName + "=\"");
+        StringJoiner joiner = new StringJoiner(File.pathSeparator, prefix, "\"");
         joiner.setEmptyValue("");
         for (Path p : paths) {
             joiner.add(p.toString());

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

@@ -68,9 +68,8 @@ default Path directory() {
      * If no syntax is specified, or if its length is 1 character (interpreted as a Windows drive),
      * the default is a Maven-specific variation of the {@code "glob"} pattern.
      *
-     * <p>
-     * The default implementation returns an empty list, which means to apply a language-dependent pattern.
-     * For example, for the Java language, the pattern includes all files with the {@code .java} suffix.
+     * <p>The default implementation returns an empty list, which means to apply a language-dependent pattern.
+     * For example, for the Java language, the pattern includes all files with the {@code .java} suffix.</p>
      *
      * @see java.nio.file.FileSystem#getPathMatcher(String)
      */

api/maven-api-core/src/test/java/org/apache/maven/api/JavaPathTypeTest.java

@@ -0,0 +1,68 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.maven.api;
+
+import java.io.File;
+import java.nio.file.Path;
+import java.util.List;
+
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+public class JavaPathTypeTest {
+    /**
+     * {@return dummy paths to use in tests}.
+     */
+    private static List<Path> paths() {
+        return List.of(Path.of("src", "foo.java"), Path.of("src", "bar.java"));
+    }
+
+    /**
+     * Converts paths from Unix style to platform-dependent style.
+     *
+     * @param expected the option value expected by the test
+     * @return the expected value with separators of the host
+     */
+    private static String toPlatformSpecific(String expected) {
+        return expected.replace("/", File.separator).replace(":", File.pathSeparator);
+    }
+
+    /**
+     * Tests the formatting of an option without module name.
+     */
+    @Test
+    public void testOption() {
+        String[] formatted = JavaPathType.MODULES.option(paths());
+        assertEquals(2, formatted.length);
+        assertEquals("--module-path", formatted[0]);
+        assertEquals(toPlatformSpecific("\"src/foo.java:src/bar.java\""), formatted[1]);
+    }
+
+    /**
+     * Tests the formatting of an option with a module name.
+     */
+    @Test
+    public void testModularOption() {
+        String[] formatted = JavaPathType.patchModule("my.module").option(paths());
+        assertEquals(2, formatted.length);
+        assertEquals("--patch-module", formatted[0]);
+        assertEquals(toPlatformSpecific("my.module=\"src/foo.java:src/bar.java\""), formatted[1]);
+    }
+}