desruisseaux commented on code in PR #1501:
URL: https://github.com/apache/maven/pull/1501#discussion_r1590432486


##########
api/maven-api-core/src/main/java/org/apache/maven/api/PathType.java:
##########
@@ -94,23 +94,24 @@ public String option(Iterable<? extends Path> paths) {
      * The path elements are separated by an option-specific or 
platform-specific separator.
      * If the given {@code paths} argument contains no element, then this 
method returns an empty string.
      *
-     * <p><b>Examples:</b>
-     * If {@code paths} is a list containing two elements, {@code path1} and 
{@code path2}, then:
-     * </p>
+     * <h4>Examples</h4>
+     * If {@code paths} is a list containing two elements, {@code dir/path1} 
and {@code dir/path2}, then:
+     *
      * <ul>
      *   <li>If this type is {@link JavaPathType#MODULES}, then this method 
returns
-     *       {@code "--module-path path1:path2"} on Unix or {@code 
"--module-path path1;path2"} on Windows.</li>
+     *       {@code {"--module-path", "dir/path1:dir/path2"}} on Unix or
+     *       {@code {"--module-path", "dir\path1;dir\path2"}} on Windows.</li>
      *   <li>If this type was created by {@code 
JavaPathType.patchModule("foo.bar")}, then the method returns
-     *       {@code "--patch-module foo.bar=path1:path2"} on Unix or {@code 
"--patch-module foo.bar=path1;path2"}
-     *       on Windows.</li>
+     *       {@code {"--patch-module", "foo.bar=dir/path1:dir/path2"}} on Unix 
or
+     *       {@code {"--patch-module", "foo.bar=dir\path1;dir\path2"}} on 
Windows.</li>
      * </ul>
      *
      * @param paths the path to format as a string
      * @return the option associated to this path type followed by the given 
path elements,
-     *         or an empty string if there is no path element.
+     *         or an empty array if there is no path element.
      */
     @Nonnull
-    String option(Iterable<? extends Path> paths);
+    String[] option(Iterable<? extends Path> paths);

Review Comment:
   The method is proposed here for two reasons: code reuse, and because the 
method behaviour depends on the option rather than the plugin using it.
   
   ### Code reuse
   The use of this method would be shared by many plugins. For example, the 
same `--class-path` option is used by `java`, `javac`, `javadoc`, `javap`, 
`jdeprscan`, `jdeps`, `jmod` and `jshell`. In current Maven architecture, those 
tools are handled by independent plugins. This method reduces the need to 
repeat the same code in all plugins.
   
   **Note:** this strategy relies on Oracle using consistently the same option 
names for all tools. It seems to be the case for all tools except `serialver`, 
provided that we use the modern form (e.g. `--class-path` instead of `-cp`).
   
   ### Who defines the behaviour
   The behaviour of this method depends on the option rather than the plugin. 
For example, `JavaPathType.CLASSES` formats the given list of files as 
`--class-path <the files>`. But `JavaPathType.patchModule("org.my.module")` 
formats the same list of files as `--patch-module org.my.module=<the files>`. 
This rule is applied consistently in at least `java`, `javac` and `javadoc`. As 
we can see, the actual work done by this method is determined by the option, 
not by the plugin, which is why the method appears in `PathType`: for allowing 
the implementation to be option-dependent.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: [email protected]

For queries about this service, please contact Infrastructure at:
[email protected]

Reply via email to