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

[David Holmes]

On Tue, 16 Jan 2024 02:21:56 GMT, Chris Plummer <cjplummer at openjdk.org> wrote:

>> But that only works if `init_value` is never called, else `is_set` will be true. This seems a rather fragile way to have the "default string" available for the help command, but avoiding actually using it as a default value.
>> 
>> That said, after having a much deeper look at how this all hangs together, it may be this will have to suffice, at least for now. Really we need a way to express that the default-string is only intended for providing the help information it is not actually intended to be parsed to "generate" the default value. But I will also note that part of the problem here is that the DCmd help needs to report the default filename, but the DCmd is not actually responsible for establishing what that default is - we have to hard-wire into the DCMd help knowledge of what the underlying API does.
>
> For the dcmd help output, we could take a dynamic approach and have the dcmd call an API (which does not currently exist) which is responsible for generating the default file name. For CDS, this would have to be an upcall to java since that is where the default filename is currently generated.
> 
> ...or we could just punt on this for now and continue with not actually specifying the default in the help output or the man page.

I don't think we want that for the help output - I think we want the generic form with the "<pid>" text, not the filename with the actual pid value inserted.

I do think we want the help and manpage to document the default filenames. So I think Ioi's suggestion is the best option at the moment. Thanks.

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

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