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

[Chris Plummer]

On Thu, 11 Jan 2024 22:11:00 GMT, Chris Plummer <cjplummer at openjdk.org> wrote:

>> The jcmd docs for Compiler.perfmap currently say:
>> 
>>     - *filename*: (Optional) The name of the map file (STRING, no default value)
>> 
>> However, there is a default, so not only should that be made more clear in the above, but also some descriptive text as to how the default is generated should be added.
>> 
>> VM.cds has a similar issue, but already has the descriptive text, so just the "no default value" part needs to be fixed.
>> 
>> Another change needed is to consistently use *filename* (italics) instead of `filename` (monospace). Note this is how html formatting is done. For the man page formatting, *filename* does no formatting and `filename` is displayed in color if supported. Personally I prefer `filename`, but it seems that there is already a strong precedence for using italics in the *arguments* list. For example:
>> 
>>     *arguments*:
>> 
>>     - *flag name*: The name of the flag that you want to set (STRING, no
>>         default value)
>> 
>>     - *string value*: (Optional) The value that you want to set (STRING, no
>>         default value)
>
> Chris Plummer has updated the pull request with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains three additional commits since the last revision:
> 
>  - Merge branch 'master' into 8323546_jcmd_doc
>    merge
>  - update jcmd help output to include default filename
>  - minor improvements related to Compiler.perfmap filename argument

Ignore my last push to update the jcmd help output. It doesn't work because it actually sets the default to the specified value, so in the case of `Compiler.perfmap`, it writes to the file `/tmp/perf-<pid>.map` where `<pid>` is literal and not expanded to the actual pid.

I don't think it is going to be possible to get the help output to display the default value since the default value varies based on the pid, and in the case of VM.cds, also depends on the `subcmd` argument.

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

PR Comment: https://git.openjdk.org/jdk/pull/17359#issuecomment-1888135435