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

[Chris Plummer]

On Tue, 16 Jan 2024 23:46:02 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 incrementally with one additional commit since the last revision:
> 
>   Fix issue with not allowing user to specify a filename that is equivalent to the default filename descripiton.

I've updated the PR with Ioi's suggestion and also added a test cast to PerfMapTest.java to make sure if the default is specified, then it actually gets used as the filename (it failed before I added Ioi's fix). Ioi, let me know if you think a similar test for VM.cds is warranted.

i also updated the javadoc to not include quotes around the default filename. This is consistent with how other defaults are printed, and also how jcmd "help" prints the default argument.

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

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