RFR: 8276265: jcmd man page is outdated

[Chris Plummer]

On Fri, 5 Nov 2021 06:19:56 GMT, David Holmes <dholmes at 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