rework documentation for new JDK-specific goals

pom.xml

@@ -28,7 +28,7 @@ under the License.
   </parent>
 
   <artifactId>maven-toolchains-plugin</artifactId>
-  <version>3.1.1-SNAPSHOT</version>
+  <version>3.2.0-SNAPSHOT</version>
   <packaging>maven-plugin</packaging>
 
   <name>Apache Maven Toolchains Plugin</name>

src/main/java/org/apache/maven/plugins/toolchain/ToolchainMojo.java

@@ -35,8 +35,8 @@
 import org.apache.maven.toolchain.ToolchainPrivate;
 
 /**
- * Check that toolchains requirements are met by currently configured toolchains and
- * store the selected toolchains in build context for later retrieval by other plugins.
+ * Check that toolchains requirements are met by currently configured toolchains in {@code toolchains.xml} and
+ * store the selected toolchain in build context for later retrieval by other plugins.
  *
  * @author mkleint
  */
@@ -61,10 +61,10 @@ public class ToolchainMojo extends AbstractMojo {
 
     /**
      * Toolchains requirements, specified by one
-     * <pre>  &lt;toolchain-type&gt;
-     *    &lt;param&gt;expected value&lt;/param&gt;
-     *    ...
-     *  &lt;/toolchain-type&gt;</pre>
+     * <pre>{@code   <toolchain-type>
+     *     <param>expected value</param>
+     *     ...
+     *   </toolchain-type>}</pre>
      * element for each required toolchain.
      */
     @Parameter(required = true)

src/main/java/org/apache/maven/plugins/toolchain/jdk/DisplayDiscoveredJdkToolchainsMojo.java

@@ -34,6 +34,8 @@
 
 /**
  * Discover the JDK toolchains and print them to the console.
+ *
+ * @since 3.2.0
  */
 @Mojo(name = "display-discovered-jdk-toolchains", requiresProject = false)
 public class DisplayDiscoveredJdkToolchainsMojo extends AbstractMojo {

src/main/java/org/apache/maven/plugins/toolchain/jdk/GenerateJdkToolchainsXmlMojo.java

@@ -36,6 +36,8 @@
 
 /**
  * Run the JDK toolchain discovery mechanism and generates a toolchains XML.
+ *
+ * @since 3.2.0
  */
 @Mojo(name = "generate-jdk-toolchains-xml", requiresProject = false)
 public class GenerateJdkToolchainsXmlMojo extends AbstractMojo {

src/main/java/org/apache/maven/plugins/toolchain/jdk/SelectJdkToolchainMojo.java

@@ -50,6 +50,8 @@
 
 /**
  * Discover JDK toolchains and select a matching one.
+ *
+ * @since 3.2.0
  */
 @Mojo(name = "select-jdk-toolchain", defaultPhase = LifecyclePhase.VALIDATE)
 public class SelectJdkToolchainMojo extends AbstractMojo {

src/main/java/org/apache/maven/plugins/toolchain/jdk/ToolchainDiscoverer.java

@@ -57,7 +57,10 @@
 import static org.apache.maven.plugins.toolchain.jdk.SelectJdkToolchainMojo.TOOLCHAIN_TYPE_JDK;
 
 /**
- * Toolchain discoverer service
+ * Toolchain discoverer service: tries {@code JAVA{xx}_HOME} environment variables, third party installers and
+ * OS-specific locations.
+ *
+ * @since 3.2.0
  */
 @Named
 @Singleton
@@ -78,7 +81,7 @@ public class ToolchainDiscoverer {
     public static final List<String> SORTED_PROVIDES = Collections.unmodifiableList(
             Arrays.asList(VERSION, RUNTIME_NAME, RUNTIME_VERSION, VENDOR, VENDOR_VERSION, CURRENT, LTS, ENV));
 
-    public static final String DISCOVERED_TOOLCHAINS_CACHE_XML = ".m2/discovered-toolchains-cache.xml";
+    public static final String DISCOVERED_TOOLCHAINS_CACHE_XML = ".m2/discovered-jdk-toolchains-cache.xml";
 
     public static final String JDK_HOME = "jdkHome";
     public static final String JAVA_HOME = "java.home";
@@ -394,18 +397,27 @@ private Set<Path> findJdks() {
         return foundJdks;
     }
 
+    /**
+     * Find JDKs in known classical locations.
+     *
+     * @return a set of path where JDKs were found.
+     */
     private Set<Path> doFindJdks() {
         List<Path> dirsToTest = new ArrayList<>();
+
         // add current JDK
         dirsToTest.add(Paths.get(System.getProperty(JAVA_HOME)));
+
         // check environment variables for JAVA{xx}_HOME
         System.getenv().entrySet().stream()
                 .filter(e -> e.getKey().startsWith("JAVA") && e.getKey().endsWith("_HOME"))
                 .map(e -> Paths.get(e.getValue()))
                 .forEach(dirsToTest::add);
+
         final Path userHome = Paths.get(System.getProperty(USER_HOME));
         List<Path> installedDirs = new ArrayList<>();
-        // jdk installed by third
+
+        // JDK installed by third-party tool managers
         installedDirs.add(userHome.resolve(".jdks"));
         installedDirs.add(userHome.resolve(".m2").resolve("jdks"));
         installedDirs.add(userHome.resolve(".sdkman").resolve("candidates").resolve("java"));
@@ -414,7 +426,8 @@ private Set<Path> doFindJdks() {
         installedDirs.add(userHome.resolve(".jbang").resolve("cache").resolve("jdks"));
         installedDirs.add(userHome.resolve(".asdf").resolve("installs"));
         installedDirs.add(userHome.resolve(".jabba").resolve("jdk"));
-        // os related directories
+
+        // OS related directories
         String osname = System.getProperty("os.name").toLowerCase(Locale.ROOT);
         boolean macos = osname.startsWith("mac");
         boolean win = osname.startsWith("win");
@@ -437,6 +450,7 @@ private Set<Path> doFindJdks() {
             installedDirs.add(Paths.get("/opt/java"));
             installedDirs.add(Paths.get("/usr/lib/jvm"));
         }
+
         for (Path dest : installedDirs) {
             if (Files.isDirectory(dest)) {
                 try (Stream<Path> stream = Files.list(dest)) {
@@ -451,6 +465,7 @@ private Set<Path> doFindJdks() {
                 }
             }
         }
+
         // only keep directories that have a javac file
         return dirsToTest.stream()
                 .filter(ToolchainDiscoverer::hasJavaC)

src/site/apt/index.apt.vm

@@ -31,20 +31,21 @@ ${project.name}
 
 * Goals Overview
 
-  Since version 3.2.0, a new toolchains mechanism is provided.  This relies on an automatic discovery mechanism based
-  on an internal heuristic which tries to detect JDK from known locations. Read about the {{{./toolchains/discovery.html}discovery mechanism}} for more
+  Since version 3.2.0, a new JDK-specific toolchains mechanism is provided.  This relies on an automatic JDK discovery mechanism based
+  on an internal heuristic which tries to detect JDKs from known locations. Read about the {{{./toolchains/jdk-discovery.html}JDK discovery mechanism}} for more
   information. This mechanism is to be used with the goal:
 
-    * {{{./toolchain-mojo.html}toolchains:select-jdk-toolchain}} discover and selects a matching toolchain.
+    * {{{./select-jdk-toolchain-mojo.html}toolchains:select-jdk-toolchain}} discover and selects a matching JDK toolchain.
 
-  Two helper goals are also provided:
+  Two associated helper goals are also provided:
 
-    * {{{./toolchain-mojo.html}toolchains:display-discovered-jdk-toolchains}} displays discovered toolchains to the console.
-    * {{{./toolchain-mojo.html}toolchains:generate-jdk-toolchains-xml}} can be used to write a <<<toolchains.xml>>> containing discovered JDKs.
+    * {{{./display-discovered-jdk-toolchains-mojo.html}toolchains:display-discovered-jdk-toolchains}} displays discovered JDK toolchains to the console,
 
-  The previous <<<toolchain>>> goal is still available:
+    * {{{./generate-jdk-toolchains-xml-mojo.html}toolchains:generate-jdk-toolchains-xml}} can be used to generate discovered JDKs in <<<toolchains.xml>>> format and let user copy/paste.
 
-    * {{{./toolchain-mojo.html}toolchains:toolchain}} selects a toolchain based on configured build requirements and stores it in build context for later retrieval by other plugins.
+  The previous <<<toolchain>>> goal is still available for JDK and {{{./toolchains/custom.html}other types}} of toolchains:
+
+    * {{{./toolchain-mojo.html}toolchains:toolchain}} selects a toolchain from <<<toolchains.xml>>> based on configured build requirements and stores it in build context for later retrieval by other plugins.
 
 * Usage
 

src/site/apt/toolchains/discovery.apt.vm → src/site/apt/toolchains/jdk-discovery.apt.vm

@@ -16,7 +16,7 @@
 ~~ under the License.
 
   ------
-  Discovery mechanism
+  JDK Discovery mechanism
   ------
   Guillaume Nodet
   ------
@@ -71,7 +71,7 @@ JDK Toolchain discovery mechanism
 
   The <<<select-jdk-toolchain>>> goal finds a matching JDK.
   The config below allows using the current JDK, or any other discovered JDK >= 17.
-  The current JDK can be kept for speed, but JDK 17 or higher will be used if the current JDK is older than 17.
+  The current JDK can be kept for speed, but JDK 17 or higher will be used if the current JDK is older than 17:
 
 +---+
 <properties>
@@ -99,6 +99,12 @@ JDK Toolchain discovery mechanism
 <properties>
   <toolchain.jdk.version>JAVA17_HOME</toolchain.jdk.version>
 <properties>
++---+
+
+  You can also do everything only at CLI level, without modifying your <<<pom.xml>>>
+
++---+
+mvn toolchains:select-jdk-toolchain -Dtoolchain.jdk.version="[17,)" compile
 +---+
 
 * Selection mechanism
@@ -135,13 +141,13 @@ JDK Toolchain discovery mechanism
 
   The default value is <<<lts,current,env,version,vendor>>>.
 
-* Toolchains XML file
+* <<<toolchains.xml>>> file
 
-  The generation of the <<<toolchains.xml>>> file is not necessary to use discovered toolchains.
-  The <<<select-jdk-toolchain>>> will select a toolchain amongst explicitly configured toolchains and discovered
-  toolchains. Discovered toolchains are cached in <<<~/.m2/discovered-toolchains-cache.xml>>> file
+  The generation of the <<<toolchains.xml>>> file is not necessary to use discovered JDK toolchains.
+  The <<<select-jdk-toolchain>>> will select a toolchain amongst explicitly configured toolchains in <<<toolchains.xml>>> and discovered
+  JDK toolchains. Discovered JDK toolchains are cached in <<<~/.m2/discovered-jdk-toolchains-cache.xml>>> file
   by default, to speed up builds.
 
-  If you prefer, you can use the <<<generate-jdk-toolchains-xml>>> to generate a toolchain XML.  This can be used in
+  If you prefer, you can use the <<<generate-jdk-toolchains-xml>>> to generate a <<<toolchains.xml>>>.  This can be used in
   conjunction with the <<<discoverToolchains=false>>> configuration to disable discovery and only use explicitly
   configured toolchains.

src/site/apt/toolchains/jdk.apt.vm

@@ -25,24 +25,24 @@
 
 JDK Toolchain
 
-Note that this page refers to hand-written JDK toolchains.  For a simpler setup, look at the {{{./discovery.html}discovery mechanism}}.
+  Note that this page refers to hand-written JDK toolchains in <<<~/.m2/toolchains.xml>>>.  For a simpler setup, look at the {{{./jdk-discovery.html}JDK discovery mechanism}}.
 
 * Toolchain Description
 
   The toolchain type id for JDK is "<<<jdk>>>".
 
   Predefined <<<\<provides\>>>> identification tokens, for requirement matching in plugin configuration, are:
 
-    * "<<<version>>>" marks the version of the JDK in <<<toolchain.xml>>>. In plugin's selection, this can be either a single version or a version range.
+    * "<<<version>>>" marks the version of the JDK in <<<toolchains.xml>>>. In plugin's selection, this can be either a single version or a version range.
 
     * Other tokens are accepted, but only exact matches are supported.
 
     []
 
-  There is only one <<<toolchains.xml>>> <<<\<configuration\>>>> element named "<<<jdkHome>>>". It designates the root directory
+  In <<<toolchains.xml>>>, there is only one <<<\<configuration\>>>> element named "<<<jdkHome>>>". It designates the root directory
   of a JDK installation.
 
-* Sample <<<toolchains.xml>>> setup
+* Sample <<<~/.m2/toolchains.xml>>> setup
 
 +---+
 <toolchains>

src/site/apt/usage.apt.vm

@@ -34,7 +34,7 @@ Usage
   tools (including location and other information).
 
   Maven Toolchains Plugin can read which toolchains are available on the user's
-  computer (as configured in <<<toolchains.xml>>>) and match them against the
+  computer (as configured in <<<~/.m2/toolchains.xml>>>) and match them against the
   toolchain requirements of the project (as configured in <<<pom.xml>>>). If a
   match is found, the toolchain is made available to other, <toolchain aware>,
   Maven plugins in the build.

src/site/site.xml

@@ -27,13 +27,13 @@ under the License.
       <item name="Introduction" href="index.html"/>
       <item name="Goals" href="plugin-info.html">
         <item name="toolchains:select-jdk-toolchain" href="select-jdk-toolchain-mojo.html"/>
-        <item name="toolchains:toolchain" href="toolchain-mojo.html"/>
-        <item name="toolchains:display-discovered-jdk-toolchains-xml" href="display-discovered-jdk-toolchains-xml-mojo.html"/>
+        <item name="toolchains:display-discovered-jdk-toolchains" href="display-discovered-jdk-toolchains-mojo.html"/>
         <item name="toolchains:generate-jdk-toolchains-xml" href="generate-jdk-toolchains-xml-mojo.html"/>
+        <item name="toolchains:toolchain" href="toolchain-mojo.html"/>
         <item name="toolchains:help" href="help-mojo.html"/>
       </item>
       <item name="Usage" href="usage.html">
-        <item name="Discovery mechanism" href="toolchains/discovery.html"/>
+        <item name="JDK Discovery Mechanism" href="toolchains/jdk-discovery.html"/>
         <item name="Standard Toolchains" href="toolchains/index.html"/>
         <item name="JDK Standard Toolchain" href="toolchains/jdk.html"/>
         <item name="Custom Toolchains" href="toolchains/custom.html"/>