8326959: Improve JVMCI option help

Reviewed-by: never

Author: Doug Simon

src/jdk.internal.vm.ci/share/classes/jdk/vm/ci/hotspot/HotSpotJVMCIRuntime.java

@@ -221,35 +221,60 @@ static String[] exceptionToString(Throwable o, boolean toString, boolean stackTr
      */
     static final Map<String, Object> options = new HashMap<>();
 
+    /**
+     * Sentinel help value to denote options that are not printed by -XX:+JVMCIPrintProperties.
+     * Javadoc is used instead to document these options.
+     */
+    private static final String[] NO_HELP = null;
+
     /**
      * A list of all supported JVMCI options.
      */
     public enum Option {
         // @formatter:off
-        Compiler(String.class, null, "Selects the system compiler. This must match the getCompilerName() value returned " +
-                "by a jdk.vm.ci.runtime.JVMCICompilerFactory provider. " +
-                "An empty string or the value \"null\" selects a compiler " +
-                "that will raise an exception upon receiving a compilation request."),
-        // Note: The following one is not used (see InitTimer.ENABLED). It is added here
-        // so that -XX:+JVMCIPrintProperties shows the option.
-        InitTimer(Boolean.class, false, "Specifies if initialization timing is enabled."),
-        CodeSerializationTypeInfo(Boolean.class, false, "Prepend the size and label of each element to the stream when " +
-                "serializing HotSpotCompiledCode to verify both ends of the protocol agree on the format. " +
-                "Defaults to true in non-product builds."),
-        DumpSerializedCode(String.class, null, "Dump serialized code during code installation for code whose simple " +
-                "name (a stub) or fully qualified name (an nmethod) contains this option's value as a substring."),
-        ForceTranslateFailure(String.class, null, "Forces HotSpotJVMCIRuntime.translate to throw an exception in the context " +
-                "of the peer runtime. The value is a filter that can restrict the forced failure to matching translated " +
-                "objects. See HotSpotJVMCIRuntime.postTranslation for more details. This option exists solely to test " +
-                "correct handling of translation failures."),
-        PrintConfig(Boolean.class, false, "Prints VM configuration available via JVMCI."),
-        AuditHandles(Boolean.class, false, "Record stack trace along with scoped foreign object reference wrappers " +
-                "to debug issue with a wrapper being used after its scope has closed."),
-        TraceMethodDataFilter(String.class, null,
-                "Enables tracing of profiling info when read by JVMCI.",
-                "Empty value: trace all methods",
-                        "Non-empty value: trace methods whose fully qualified name contains the value."),
-        UseProfilingInformation(Boolean.class, true, "");
+        Compiler(String.class, null,
+                "Selects the system compiler. This must match the getCompilerName() value",
+                "returned by a jdk.vm.ci.runtime.JVMCICompilerFactory provider. ",
+                "An empty string or the value \"null\" selects a compiler ",
+                "that raises an exception upon receiving a compilation request."),
+
+        PrintConfig(Boolean.class, false, "Prints VM values (e.g. flags, constants, field offsets etc) exposed to JVMCI."),
+
+        InitTimer(Boolean.class, false, NO_HELP),
+
+        /**
+         * Prepends the size and label of each element to the stream when serializing {@link HotSpotCompiledCode}
+         * to verify both ends of the protocol agree on the format. Defaults to true in non-product builds.
+         */
+        CodeSerializationTypeInfo(Boolean.class, false, NO_HELP),
+
+        /**
+         * Dumps serialized code during code installation for code whose qualified form (e.g.
+         * {@code java.lang.String.hashCode()}) contains this option's value as a substring.
+         */
+        DumpSerializedCode(String.class, null, NO_HELP),
+
+        /**
+         * Forces {@link #translate} to throw an exception in the context of the peer runtime for
+         * translated objects that match this value. See {@link #postTranslation} for more details.
+         * This option exists solely to test correct handling of translation failures.
+         */
+        ForceTranslateFailure(String.class, null, NO_HELP),
+
+        /**
+         * Captures a stack trace along with scoped foreign object reference wrappers
+         * to debug an issue with a wrapper being used after its scope has closed.
+         */
+        AuditHandles(Boolean.class, false, NO_HELP),
+
+        /**
+         * Enables tracing of profiling info when read by JVMCI.
+         *     Empty value: trace all methods
+         * Non-empty value: trace methods whose fully qualified name contains the value
+         */
+        TraceMethodDataFilter(String.class, null, NO_HELP),
+
+        UseProfilingInformation(Boolean.class, true, NO_HELP);
         // @formatter:on
 
         /**
@@ -343,6 +368,9 @@ public static void printProperties(PrintStream out) {
             out.println("[JVMCI properties]");
             Option[] values = values();
             for (Option option : values) {
+                if (option.helpLines == null) {
+                    continue;
+                }
                 Object value = option.getValue();
                 if (value instanceof String) {
                     value = '"' + String.valueOf(value) + '"';
@@ -362,6 +390,7 @@ public static void printProperties(PrintStream out) {
                 for (String line : option.helpLines) {
                     out.printf("%" + PROPERTY_HELP_INDENT + "s%s%n", "", line);
                 }
+                out.println();
             }
         }
 

test/hotspot/jtreg/compiler/jvmci/TestJVMCIPrintProperties.java

@@ -24,7 +24,7 @@
 /*
  * @test TestBasicLogOutput
  * @bug 8203370
- * @summary Ensure -XX:-JVMCIPrintProperties can be enabled and successfully prints expected output to stdout.
+ * @summary Ensure -XX:+JVMCIPrintProperties successfully prints expected output to stdout.
  * @requires vm.flagless
  * @requires vm.jvmci
  * @library /test/lib
@@ -49,9 +49,7 @@ static void test(String enableFlag) throws Exception {
         OutputAnalyzer output = new OutputAnalyzer(pb.start());
         output.shouldContain("[JVMCI properties]"); // expected message
         output.shouldContain("jvmci.Compiler := \"null\""); // expected message
-        output.shouldContain("jvmci.InitTimer = false"); // expected message
         output.shouldContain("jvmci.PrintConfig = false"); // expected message
-        output.shouldContain("jvmci.TraceMethodDataFilter = null"); // expected message
         output.shouldHaveExitValue(0);
     }
 }