8318962: Update ProcessTools javadoc with suggestions in 8315097

Backport-of: 7e4cb2f09d1219c6ba7bfa77be831a7c7c9b055a

test/lib/jdk/test/lib/process/ProcessTools.java

@@ -492,12 +492,21 @@ private static void printStack(Thread t, StackTraceElement[] stack) {
     }
 
     /**
-     * Create ProcessBuilder using the java launcher from the jdk to be tested.
-     * The default jvm options from jtreg, test.vm.opts and test.java.opts, are added.
-     * <p>
-     * The command line will be like:
-     * {test.jdk}/bin/java {test.vm.opts} {test.java.opts} cmds
-     * Create ProcessBuilder using the java launcher from the jdk to be tested.
+     * Create ProcessBuilder using the java launcher from the jdk to
+     * be tested. The default jvm options from jtreg, test.vm.opts and
+     * test.java.opts, are added.
+     *
+     * <p>Unless the "test.noclasspath" property is "true" the
+     * classpath property "java.class.path" is appended to the command
+     * line and the environment of the ProcessBuilder is modified to
+     * remove "CLASSPATH". If the property "test.thread.factory" is
+     * provided the command args are updated and appended to invoke
+     * ProcessTools main() and provide the name of the thread factory.
+     *
+     * <p>The "-Dtest.thread.factory" is appended to the arguments
+     * with the thread factory value. The remaining command args are
+     * scanned for unsupported options and are appended to the
+     * ProcessBuilder.
      *
      * @param command Arguments to pass to the java command.
      * @return The ProcessBuilder instance representing the java command.
@@ -507,12 +516,21 @@ public static ProcessBuilder createTestJavaProcessBuilder(List<String> command)
     }
 
     /**
-     * Create ProcessBuilder using the java launcher from the jdk to be tested.
-     * The default jvm options from jtreg, test.vm.opts and test.java.opts, are added.
-     * <p>
-     * The command line will be like:
-     * {test.jdk}/bin/java {test.vm.opts} {test.java.opts} cmds
-     * Create ProcessBuilder using the java launcher from the jdk to be tested.
+     * Create ProcessBuilder using the java launcher from the jdk to
+     * be tested. The default jvm options from jtreg, test.vm.opts and
+     * test.java.opts, are added.
+     *
+     * <p>Unless the "test.noclasspath" property is "true" the
+     * classpath property "java.class.path" is appended to the command
+     * line and the environment of the ProcessBuilder is modified to
+     * remove "CLASSPATH". If the property "test.thread.factory" is
+     * provided the command args are updated and appended to invoke
+     * ProcessTools main() and provide the name of the thread factory.
+     *
+     * <p>The "-Dtest.thread.factory" is appended to the arguments
+     * with the thread factory value. The remaining command args are
+     * scanned for unsupported options and are appended to the
+     * ProcessBuilder.
      *
      * @param command Arguments to pass to the java command.
      * @return The ProcessBuilder instance representing the java command.
@@ -536,6 +554,18 @@ public static ProcessBuilder createTestJavaProcessBuilder(String... command) {
      * it in combination with <b>@requires vm.flagless</b> JTREG
      * anotation as to not waste energy and test resources.
      *
+     * <p>Unless the "test.noclasspath" property is "true" the
+     * classpath property "java.class.path" is appended to the command
+     * line and the environment of the ProcessBuilder is modified to
+     * remove "CLASSPATH". If the property "test.thread.factory" is
+     * provided the command args are updated and appended to invoke
+     * ProcessTools main() and provide the name of the thread factory.
+     *
+     * <p>The "-Dtest.thread.factory" is appended to the arguments
+     * with the thread factory value. The remaining command args are
+     * scanned for unsupported options and are appended to the
+     * ProcessBuilder.
+     *
      * @param command Arguments to pass to the java command.
      * @return The ProcessBuilder instance representing the java command.
      */
@@ -558,6 +588,18 @@ public static ProcessBuilder createLimitedTestJavaProcessBuilder(List<String> co
      * it in combination with <b>@requires vm.flagless</b> JTREG
      * anotation as to not waste energy and test resources.
      *
+     * <p>Unless the "test.noclasspath" property is "true" the
+     * classpath property "java.class.path" is appended to the command
+     * line and the environment of the ProcessBuilder is modified to
+     * remove "CLASSPATH". If the property "test.thread.factory" is
+     * provided the command args are updated and appended to invoke
+     * ProcessTools main() and provide the name of the thread factory.
+     *
+     * <p>The "-Dtest.thread.factory" is appended to the arguments
+     * with the thread factory value. The remaining command args are
+     * scanned for unsupported options and are appended to the
+     * ProcessBuilder.
+     *
      * @param command Arguments to pass to the java command.
      * @return The ProcessBuilder instance representing the java command.
      */
@@ -566,14 +608,12 @@ public static ProcessBuilder createLimitedTestJavaProcessBuilder(String... comma
     }
 
     /**
-     * Executes a test jvm process, waits for it to finish and returns the process output.
-     * The default jvm options from jtreg, test.vm.opts and test.java.opts, are added.
-     * The java from the test.jdk is used to execute the command.
-     * <p>
-     * The command line will be like:
-     * {test.jdk}/bin/java {test.vm.opts} {test.java.opts} cmds
-     * <p>
-     * The jvm process will have exited before this method returns.
+     * Executes a test jvm process, waits for it to finish and returns
+     * the process output.
+     *
+     * <p>The process is created using runtime flags set up by:
+     * {@link #createTestJavaProcessBuilder(String...)}. The
+     * jvm process will have exited before this method returns.
      *
      * @param cmds User specified arguments.
      * @return The output from the process.
@@ -583,14 +623,12 @@ public static OutputAnalyzer executeTestJvm(List<String> cmds) throws Exception
     }
 
     /**
-     * Executes a test jvm process, waits for it to finish and returns the process output.
-     * The default jvm options from jtreg, test.vm.opts and test.java.opts, are added.
-     * The java from the test.jdk is used to execute the command.
-     * <p>
-     * The command line will be like:
-     * {test.jdk}/bin/java {test.vm.opts} {test.java.opts} cmds
-     * <p>
-     * The jvm process will have exited before this method returns.
+     * Executes a test jvm process, waits for it to finish and returns
+     * the process output.
+     *
+     * <p>The process is created using runtime flags set up by:
+     * {@link #createTestJavaProcessBuilder(String...)}. The
+     * jvm process will have exited before this method returns.
      *
      * @param cmds User specified arguments.
      * @return The output from the process.