[7u10] Request for approval: 7166055: Javadoc for WeakHashMap contains misleading advice

[Andrew Hughes]

----- Original Message -----
> On 16/09/2012 1:26 AM, Phil Race wrote:
> > On 9/15/12 3:46 AM, David Holmes wrote:
> >> Phil,
> >>
> >> On 15/09/2012 2:57 AM, Phil Race wrote:
> >>> I really don't think its appropriate to push javadoc changes into
> >>> an
> >>> update release without
> >>> a really, really compelling reason that I don't see here.
> >>
> >> That is certainly true if they represent a specification change,
> >> but
> >> there is no semantic change here this is a simple clarification.
> >
> > That would just rule it out completely. But we don't even
> > regenerate
> > javadoc for
> > the update releases and we have never randomly backported doc
> > comments, for
> > no obvious reason. So my reasoning and position stands.
> 
> This is OpenJDK, it doesn't matter if "we" don't regenerate javadoc
> for
> update releases. And I have long thought that "we" should! I
> understand
> the issue with spec changes in update releases but I never understood
> a
> policy that would allow errors, misconceptions and mis-guidance to be
> set in stone instead of correcting them for the benefit of the user
> community.
> 

+1

GNU/Linux distributions will make use of this new documentation in new builds,
even if the copies on the Oracle website aren't updated.  The fact that you don't
want to jump through whatever hoops are needed to update your own copies should not
stop people from making minor updates (clarifications, typo fixes) at the OpenJDK level.

I don't know how often jdk7u builds with docs are done at Oracle but there are currently
a number of warnings being thrown out by the build:

../../src/share/classes/java/awt/color/ICC_Profile.java:1069: warning - Tag @see: missing '#': "activateDeferredProfile()"
../../src/share/classes/java/lang/invoke/MethodHandle.java:392: warning - Tag @link: reference not found: Objects.equals java.util.Objects#equals
../../src/share/classes/java/util/Calendar.java:1717: warning - Tag @see: can't find setInternallySetState(int) in java.util.Calendar
../../src/share/classes/java/util/Currency.java:685: warning - @throws tag has no arguments.
../../src/share/classes/javax/swing/plaf/nimbus/NimbusStyle.java:854: warning - @return tag has no arguments.
../../src/share/classes/javax/swing/plaf/nimbus/NimbusStyle.java:926: warning - @return tag has no arguments.
/home/andrew/builder/icedtea-jdk7/impsrc/javax/xml/bind/JAXBContext.java:262: warning - Tag @see: reference not found: S 7.4.1 "Named Packages" in Java Language Specification</a>
7 warnings

Are we supposed to retain these too?  I can probably provide webrevs to fix these, but there's
no point if they aren't going to be accepted.

> David
> 
> > -phil.
> >
> >>
> >> David
> >> ------
> >>
> >>> A reminder: Update releases aren't a free-for-all. You need to
> >>> exercise
> >>> judgement in what
> >>> has to go in and what is the case for it. We are up to 7u10 now.
> >>> We need
> >>> to be dialling
> >>> back the rate of change and focusing on JDK 8.
> >>>
> >>> -phil.
> >>>
> >>>
> >>> On 9/14/2012 12:56 AM, Shi Jun Zhang wrote:
> >>>> Hi all,
> >>>>
> >>>> I'd like to request for approval to push the following change
> >>>> into
> >>>> 7u10.
> >>>>
> >>>> Changeset in jdk8
> >>>> http://hg.openjdk.java.net/jdk8/tl/jdk/rev/237e27c7ddc3
> >>>>
> >>>> Webrev
> >>>> http://cr.openjdk.java.net/~zhangshj/jdk7u/7166055/webrev.00/
> >>>>
> >>>> Reviewed by dholmes, mduigou
> >>>>
> >>>> Review thread
> >>>> http://mail.openjdk.java.net/pipermail/core-libs-dev/2012-May/010322.html
> >>>>
> >>>>
> >>>
> >
> 

-- 
Andrew :)

Free Java Software Engineer
Red Hat, Inc. (http://www.redhat.com)

PGP Key: 248BDC07 (https://keys.indymedia.org/)
Fingerprint = EC5A 1F5E C0AD 1D15 8F1F  8F91 3B96 A578 248B DC07