(13) RFR (S): 8227055: Minor edits to launcher help text

[Mandy Chung]

On 7/2/19 11:10 PM, David Holmes wrote:
> Hi Mandy,
>
> Thanks for taking a look.
>
> On 3/07/2019 8:57 am, Mandy Chung wrote:
>> On 7/2/19 3:44 PM, David Holmes wrote:
>>> webrev: http://cr.openjdk.java.net/~dholmes/8227055/webrev/
>>> bug: https://bugs.openjdk.java.net/browse/JDK-8227055
>>>
>>> The launcher help text needs some minor updates/corrections
>>> - -verbose needs more info
>>> - -Xdebug needs to say it does nothing
>>
>> Should this be removed instead?
>
> There is some strange history/status with this flag. I expect the flag 
> and thus documentation should be removed, but that would be a seperate 
> issue for 14 (or later). For 13 I'm just aligning the help text with 
> the manpage description.
>

I would propose  to take -Xdebug out from the launcher help message and 
man page but -Xdebug is still accepted but do nothing.

>>> - -Xloggc is deprecated and replaced by -Xlog:gc:filename
>>
>> I think it can just list -Xlog:gc<file> (the replacement) and no need
>> to mention the deprecated option in the launcher help message.
>
> Again this aligns with the manpage which does list it as deprecated 
> and its replacement. Otherwise the launcher help doesn't document 
> specific -Xlog usages.
>

-Xloggc was deprecated since 9 (or earlier [1]).  I think documenting 
the recommended option instead is the right thing to do.  I think it 
worths the discussion and includes some guideline in JEP 293 (Guidelines 
for JDK CLI) [2] w.r.t. deprecated options in the help message vs man page.

I'm fine if you want to move ahead with this patch.

>>> - -Xshare:on needs warning about use
>>>
>>> Reference to Mac OS X should be macOS.
>>>
>>> The --disable- at files is documented as both a standard and extra option.
>>>
>>
>> I think this is intended to be an extra option.
>
> This is from Alan:
>
> "I'm not sure how `-disable- at files` ended up in both the `-help` and 
> `-X` output, it probably make sense to drop it from the `-X` output. 
> That way, `@argument` and `-disable- at files` are listed together, not 
> in separate usage pages."
>
> (The bug explains how it ended up in both places - and yes it started 
> as a -X option.)
>

Hmm... Alan and Jon are both on vacation.  We can follow up this 
separately.

Mandy
[1] https://bugs.openjdk.java.net/browse/JDK-8170636
[2] https://openjdk.java.net/jeps/293