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

I found a solution. I compare the filename to the default (the descriptive default, not the actual generated default), and if it is the same then the filename is changed to nullptr, which triggers the code that uses it to generate the default file name.

@dholmes-ora @iklam Can you please have a look?

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

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