I'd like to see the help output for clhsdb improved. Clhsdb help is currently very minimal, and often you need to experiment or look at the code to figure out how a command really works. The "help" command only gives you the syntax of each command. It does not explain what the command does, nor provide details describing the contents of the options passed. For example:

hsdb> help
Available commands:
  assert true | false
  attach pid | exec core
  buildreplayjars [ all | app | boot ] | [ prefix ]
  class name
  classes
  detach
  dis address [length]
  disassemble address
  ...

Using "help <cmd>" just provides the above output for the individual command:

hsdb> help assert
Usage: assert true | false

Note we have no other documentation for clhsdb, other than the unpublished clhsdb.html file. You might be able to find some blogs that talk about some of the more useful commands, but that's about it.

The main improvement I'd like to make is to provide more details when "help <cmd>" is used. For example:

hsdb> help classes
Usage: classes
  Prints the entire dictionary of loaded classes. The output includes the class name and
  address of each VM Klass object, including for array classes. The Klass object can be passed
  to other commands that take a VM object such as "inspect".

Another change I'd like to make is to the naming of arguments. Besides being more consistent with the naming across different commands, I'd like to bracket them with "<>". This makes it easier to describe the arguments in the help output:

hsdb> help dis
Usage: dis <address> [<length>]
  Disassemble the native code located at <address>. <length> byte are disassembled.

Next I want to add an options to the "help" command that will dump commands together based on their logical grouping. First the syntax of help would become:

hsdb> help { <cmd> | topics | -t <topic> }

hsdb> help topics
  The following topics are available for help. Use "help -t <topic>" for more informaton about the topic:
    vmstructs: commands related to vmstructs
    compiler: commands useful for debugging the hotspot compiler
    heap: commands useful for debugging the java heap
    memory: commands useful for to searching and examining memory
    ...

hsdb> help -t heap
  The following commands are useful for debugging the java heap:
    dumpheap [filename]
    g1regiondetails
    jhisto
    inspect expression
    revptrs address
    scanoops start end [ type ]
    universe
    search [ heap | perm | rawheap | codecache | threads ] value

Some commands may appear under more than one topic, such as the inspect command.

Lastly, some sort of "recipes" help would be useful. For example "How to display the value of static fields of a java class". I haven't quite figured out how to work this part into the help output.

Before embarking on the code changes, we first need a source document that will contain all the needed help info. I started on this a while back but never completed it and probably won't get back to it. I'm attaching it as a reference in case this is picked up in the future.

Note an alternative to improving the help output is to just have a more complete clhsdb document (something that is a lot better than clhsdb.html) and actually publish it. See JDK-8279122 which suggest that we improve clhsdb.html and publish it.