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