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

[David Holmes]

On Mon, 15 Jan 2024 08:13:10 GMT, Ioi Lam <iklam at openjdk.org> wrote:

>> @iklam but IIUC that does not address the issue of updationg the help output.
>
> My suggestion is to be used in combination with this change:
> 
> 
> _filename("filename", "Name of the map file", "STRING", false, DEFAULT_PERFMAP_FILENAME)
> 
> 
> So the help message will be printed as: 
> 
> 
> *filename*: (Optional) The name of the map file (STRING /tmp/perf-<pid>.map)

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.

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

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