RFR 8182118: Package summary is missing in jdk.security.auth module

[Weijun Wang]

On 06/19/2017 07:52 PM, Sean Mullan wrote:
> On 6/19/17 12:33 AM, Mandy Chung wrote:
>>
>>> On Jun 18, 2017, at 8:33 PM, Weijun Wang <weijun.wang at oracle.com> wrote:
>>>
>>> Hi All
>>>
>>> Please take a review at
>>>
>>>    http://cr.openjdk.java.net/~weijun/8182118/webrev.00/
>>>
>>> Basically, a description line is added into package-info.java of each 
>>> of these packages:
>>>
>>> - com/sun/security/auth:
>>>
>>>   Contains the implementation of {@code java.security.Principal}.
> 
> There is more than one, so this should be "implementations".

In fact, I originally used "implementations" (without "the") and "an 
implementation", but then I saw the module-info.java for the module 
saying "Contains the implementation of the javax.security.auth.* 
interfaces" and thought "the implementation" is always correct.

> 
>>> - com/sun/security/auth/module:
>>>
>>>   Contains the implementation of {@code 
>>> javax.security.auth.spi.LoginModule}.
>>>
>>> - com/sun/security/auth/login:
>>>
>>>   Contains the implementation of {@code 
>>> javax.security.auth.login.Configuration}.
> 
> There is more than one, so this should be "implementations".
> 
>>> - com/sun/security/auth/callback:
>>>
>>>   Contains the implementation of {@code 
>>> javax.security.auth.callback.Callback}.
> 
> Shouldn't this be "CallbackHandler"?

Ah, yes.

> 
>> What about “Provides the implementation of ….”
> 
> +1, but I prefer "Provides an implementation of ..."
> 
> "the" sounds like this can be the one and only implementation. "an" 
> sounds better.

Thanks
Max

> 
> --Sean
> 
>> I suggest to use @link to the type.
>>
>>> with @since 1.4.
>>>
>>> I thought about using {@link java.security.Principal} but seems it's 
>>> not supported in package-info.java.
>>
>> java/lang/package-info.java and many package summary use @link.
>>
>>>
>>> BTW, is this bug meant for JDK 9? I just read the mail from Mark 
>>> saying only P1 fixes will be allowed from now on.
>>
>> If you push it your Monday, you should be able to make jdk-9+175 
>> integration (6/22 GAC).  Otherwise P1 fixes only.
>>
>> Mandy
>>