<Swing Dev> JDK 9 RFR of JDK-8077095: Fix missing doclint warnings in the javax.swing.plaf.basic package

[joe darcy]

Hello Sergey,

On 4/8/2015 7:37 AM, Sergey Bylokhov wrote:
> Hi, Joe.
> What is the benefit of /** {@inheritDoc} */ ?(which are formatted 
> differently in different files) Probably simple @Override will be more 
> helpful?

The essence of this bug fix is adding some explicit javadoc to each 
public or protected declaration. Having "{@inheritDoc}" explicitly says 
"just use the javadoc of some supertype; I have nothing to add," which 
makes the intent clear in the source code even if the generated javadoc 
is the same as if the {@inheritDoc} were omitted and the javadoc default 
action used. (I would prefer if javadoc allowed you to specify which 
supertype the {@inheritDoc} came from, but that RFE has not been 
implemented.)

For the variation in different files, If the code seemed to be using a 
dense style, I tried to use

     /** {@inheritDoc} */

rather than

     /**
      * {@inheritDoc}
     */

to conserve vertical space.

The @Override annotation is related in that the method must be 
overriding one defined in a supertype (and it is good coding practice), 
but doesn't directly interact with the javadoc generation.

>
> BasicFileChooserUI.java: openDialogTitleText/saveDialogTitleText 
> should mention that these are title text.

I'll make that edit.

> BasicInternalFrameUI.java: all text fields is in a lowcase unlike 
> other files, is it expected?

I'll change those to be

      /** Border listener */

rather than

      /** border listener */

etc.

Thanks,

-Joe

>
> On 08.04.15 10:28, joe darcy wrote:
>> Hello,
>>
>> Please review the large but mostly straightforward changes to address:
>>
>>     JDK-8077095: Fix missing doclint warnings in the 
>> javax.swing.plaf.basic package
>>     http://cr.openjdk.java.net/~darcy/8077095.0/
>>
>> This is the last large piece needed to fix the missing doclint in the 
>> client libraries. (Thankfully!)
>>
>> Thanks,
>>
>> -Joe
>
>