RFR: 8276265: jcmd man page is outdated

[David Holmes]

On Wed, 10 Nov 2021 17:13:59 GMT, Chris Plummer <cjplummer 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.

@plummercj seems to me that the help text is where the error was introduced. If you say "If x then .... Otherwise ..." the "otherwise" is equivalent to "not x" because X was the subject of the previous sentence. So the help text should not be using otherwise the way that it does as the subject is wrong - it wants the subject to the use of the -s option. What the help text should say is something like:

-s:  [optional]  If a classname is specified print its subclasses. Without this option only the superclasses would be printed.

-------------

PR: https://git.openjdk.java.net/jdk/pull/6271