RFR: 8029451 : Tidy warnings cleanup for java.util package

[Martin Buchholz]

Hi Joe,

You and I know that readObject and writeObject are very special private
methods, since they are effectively part of the public API.  Apparently,
the unexpectedly clever javadoc tool knows this as well, so even with
default flags, it will report warnings for these methods.

Notice the "Generating /tmp/t8/serialized-form.html..." below.

src/share/classes/java/util $ (mkdir -p /tmp/t8 && ~/jdk/jdk8/bin/javadoc
-d /tmp/t8 ArrayList.java)
Loading source file ArrayList.java...
Constructing Javadoc information...
Standard Doclet version 1.8.0-ea
Building tree for all the packages and classes...
Generating /tmp/t8/java/util/ArrayList.html...
Generating /tmp/t8/java/util/package-frame.html...
Generating /tmp/t8/java/util/package-summary.html...
Generating /tmp/t8/java/util/package-tree.html...
Generating /tmp/t8/constant-values.html...
Generating /tmp/t8/serialized-form.html...
ArrayList.java:759: warning: no @param for s
    private void readObject(java.io.ObjectInputStream s)
                 ^
ArrayList.java:759: warning: no @throws for java.io.IOException
    private void readObject(java.io.ObjectInputStream s)
                 ^
ArrayList.java:759: warning: no @throws for java.lang.ClassNotFoundException
    private void readObject(java.io.ObjectInputStream s)
                 ^
ArrayList.java:736: warning: no @param for s
    private void writeObject(java.io.ObjectOutputStream s)
                 ^
ArrayList.java:736: warning: no @throws for java.io.IOException
    private void writeObject(java.io.ObjectOutputStream s)
                 ^
Building index for all the packages and classes...


On Fri, Dec 6, 2013 at 9:56 AM, Joe Darcy <joe.darcy at oracle.com> wrote:

> On 12/06/2013 09:20 AM, Martin Buchholz wrote:
>
>> FYI: When I run javadoc on jsr166 CVS (it's not too hard for y'all to do
>> this as well), I still see many warnings inherited from openjdk8 source:
>>
>>   $ ant docs
>> ...
>>    [javadoc] Constructing Javadoc information...
>>    [javadoc] Standard Doclet version 1.8.0-ea
>>    [javadoc] Building tree for all the packages and classes...
>>    [javadoc]
>> /home/martin/jdk/src/jdk8/jdk/src/share/classes/java/util/
>> ArrayList.java:759:
>> warning: no @param for s
>>    [javadoc]     private void readObject(java.io.ObjectInputStream s)
>>    [javadoc]                  ^
>>    [javadoc]
>>
>
> We have been working to address doclint issues against public and
> protected elements, which is not to say readObject and writeObject methods
> shouldn't have javadoc.
>
> -Joe
>
>