RFR: 8323546: Clarify docs for Compiler.perfmap filename parameter, and other misc related jcmd doc cleanups [v4]

[David Holmes]

On Sun, 14 Jan 2024 01:26:25 GMT, Chris Plummer <cjplummer at openjdk.org> wrote:

>> I only expected to see a change to the help string, I don't understand why the actual Dcmd is being modified here! ???
>
> The default value for the argument is what gets displayed in the help text. For example:
> 
> 
> ThreadDumpToFileDCmd::ThreadDumpToFileDCmd(outputStream* output, bool heap) :
>                                            DCmdWithParser(output, heap),
>   _overwrite("-overwrite", "May overwrite existing file", "BOOLEAN", false, "false"),
>   _format("-format", "Output format ("plain" or "json")", "STRING", false, "plain"),
>   _filepath("filepath", "The file path to the output file", "STRING", true) {
>   _dcmdparser.add_dcmd_option(&_overwrite);
>   _dcmdparser.add_dcmd_option(&_format);
>   _dcmdparser.add_dcmd_argument(&_filepath);
> }
> 
> 
> And the help text:
> 
> 
> Options: (options must be specified using the <key> or <key>=<value> syntax)
> 	-overwrite : [optional] May overwrite existing file (BOOLEAN, false)
> 	-format : [optional] Output format ("plain" or "json") (STRING, plain)
> 
> 
> The help output that indicates that "plain" is the default format comes from the intialization of the _format argument. There is no separate help text.

Ugghh! So the help text is an actual stringification of the actual default value of the "field", whereas in this case the real default value comes from passing null to `CodeCache::write_perf_map`. So we need this hack to deal with that. That is truly awful IMO. The only way to cleanly address that is to expand things so that you can set an actual help string to be used.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/17359#discussion_r1451850960