RFR: 8337276: jcmd man page update for PID in output filenames

[Kevin Walls]

On Fri, 9 Aug 2024 17:50:26 GMT, Chris Plummer <cjplummer at openjdk.org> wrote:

>> OK yes - my thinking is:
>> 
>> They are strings of course, but they are also names of an output FILE, and those are distinct because they do %p substitution.
>> 
>> They need to have a "type" of FILE internally in the tool, so they get %p substitution.
>> 
>> The FILE instead of STRING doesn't need to be in the man page, but it would make sense that the man page is the same as the live help output as much as possible.
>> 
>> After the intro, the body of the man page mostly duplicates the online help for the commands.
>> So much so that you'd think we can automate that, which would make a great future step.
>> Then we would get FILE for the type of these arguments, not STRING.  So I used FILE here as it avoids a future issue.
>> 
>> I think we should move other output file names e.g. in the JFR commands to FILE over time, after verifying they do the %p substitution.  There could be %t timestamp as well, I think an enhancement request for that exists.
>> 
>> Then the docs could summarise everything about the FILE parameters and not have to duplicate it every time.
>
> Ok. I see now that [JDK-8334492](https://bugs.openjdk.org/browse/JDK-8334492) made the STRING -> FILE change, so yes the docs should be consistent, but I think we need a new CR filed to cleanup JFR dcmds, which continue to use STRING. This probably should have been done with [JDK-8334492](https://bugs.openjdk.org/browse/JDK-8334492).

Thanks, yes should have made this clearer and yes will follow up on the additional commands, we should transition them to the same language.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/20401#discussion_r1711996722