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

[David Holmes]

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

Thanks Mandy - much appreciated! We can continue this refinement for 14.

I have filed JDK-8227229 to deprecate and remove Xdebug - for history see:

https://bugs.openjdk.java.net/browse/JDK-6272174

BTW thanks for the reference to JEP-293, I wasn't aware of it. Would be 
nice to expand it to give more guidelines on handling deprecation etc.

Cheers,
David
-----

On 4/07/2019 3:36 am, Mandy Chung wrote:
> 
> 
> 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
>