On Fri, 5 Nov 2021 06:19:56 GMT, David Holmes <dhol...@openjdk.org> wrote:
> It was noticed that a number of updates to the jcmd subcommands (some new, > some modified) had not been added to the manpage. The text was supplied by > @tstuefe - thanks Thomas. I applied the changes to the closed markdown > sources and regenerated the nroff file. For easier review I have generated a > html version that can be viewed here: > > https://htmlpreview.github.io/https://github.com/dholmes-ora/jdk/blob/57c00815460ffef201239eafac322b4dd246da1b/jcmd.html > > Summary of changes: > > New Commands: > - Compiler.perfmap > - System.trim_native_heap > - VM.cds > - VM.classloaders > - VM.events > - VM.metaspace > > Missing flags: > - GC.class_histogram -parallel > - GC.heap_dump - gz and overwrite options > - Thread.print -e > > There are further improvements that could be made, some mentioned in the bug > report. I also noticed a general confusion between arguments and options with > some subcommands, but I did not try to address that. > > Thanks, > David While skimming through the entire man page, I stumbled across `VM.class_hierarchy`, a dcmd I wrote long ago. It says the following: -s: (Optional) If a class name is specified, it prints the subclasses. If the class name is not specified, only the superclasses are printed. (BOOLEAN, false) I couldn't decipher what this really meant, so I ran the dcmd and it became more obvious how the option worked, and also became obvious that the above is wrong. The help output has it right: -s : [optional] If a classname is specified, print its subclasses. Otherwise only its superclasses are printed. (BOOLEAN, false) So `jcmd VM.class_hierarchy Throwable` just prints: java.lang.Object/null |--java.lang.Throwable/null Whereas `jcmd VM.class_hierarchy -s Throwable` not only prints the above, but includes the hierarchy of every subclass of Throwable. In the man page help, adding "If the class name is not specified" is wrong. The intent of the help output is "If the class name IS specified and -s IS NOT specified...". There are probably improvements that can be made to the help output, but as it stands the man page help is wrong and at the very least should revert back to the help output. If you want me to work on something a bit better than the help output, I can do that. ------------- PR: https://git.openjdk.java.net/jdk/pull/6271
