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

Neil Richards neil.richards at ngmr.net
Tue Oct 16 09:32:23 PDT 2012 

Now pushed to jdk7u-dev/jdk [1].

Regards,
Neil

[1] http://hg.openjdk.java.net/jdk7u/jdk7u-dev/jdk/rev/63a844e1449f

On Thu, 2012-09-27 at 11:46 +0100, Seán Coffey wrote:
> Thanks for clarifying Joe. I understand that the decision here was quite 
> straight forward here with respect to updating javadocs. However, there 
> are occasions where determining what is and is not allowed in javadoc 
> updates (for an update release) is more complicated. Any suggestions on 
> process there and who the "go to" should be ?
> 
> Shi Jun - I'll update the bug report when I see the push made to jdk7u-dev.
> 
> regards,
> Sean.
> 
> On 26/09/2012 01:37, Joe Darcy wrote:
> > Hello,
> >
> > Catching up on email, I'm responding to this thread with my ccc 
> > chairman hat on.  The ccc is (currently) an Oracle-internal process 
> > which reviews API and other interfaces changes of the JDK.  The ccc is 
> > alluded to in the OpenJDK Developers' Guide [1] and among the ccc's 
> > roles is looking after the general evolution policy of the JDK [2].
> >
> > For the proposed change for 7166055, I think it is clearly an 
> > *informative* change to the text and *not* a *normative* change to the 
> > specification of WeakHashMap.  The affected paragraph starts with 
> > "Implementation Note" and then goes on to give some usage advice.  
> > Therefor, this is not a specification change that would have 
> > conformance impact and on that matter it is fine for a 7 update release.
> >
> > FWIW, my personal preference would be to have more such clarifications 
> > to the javadoc made between platform releases so that if the javadoc 
> > is regenerated, more helpful text is available.
> >
> > Cheers,
> >
> > -Joe
> >
> > [1] http://openjdk.java.net/guide/changePlanning.html
> >
> > [2] 
> > http://cr.openjdk.java.net/~darcy/OpenJdkDevGuide/OpenJdkDevelopersGuide.v0.777.html#general_evolution_policy
> >
> > On 9/18/2012 10:30 AM, Seán Coffey wrote:
> >> I'd have to agree with allowing minor/simple javadoc updates also 
> >> where specification changes are not implied. Even though Oracle 
> >> mightn't always update their javadocs it shouldn't stop others from 
> >> doing so (again for minor/simple/typo updates)
> >>
> >> I've run into arguments in past tough around what sort of javadoc 
> >> updates do and do not imply spec. changes. Let's check with 
> >> conformance team before deciding if this change is ok for an update 
> >> release.
> >>
> >> Regards,
> >> Sean.
> >>
> >> On 18/09/2012 15:51, Andrew Hughes wrote:
> >>>
> >>> ----- 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 
> >>>>>>>>
> >>>>>>>>
> >>>>>>>>
> >>
> >
> 
> _______________________________________________
> conformance-discuss mailing list
> conformance-discuss at openjdk.java.net
> http://mail.openjdk.java.net/mailman/listinfo/conformance-discuss


-- 
Unless stated above:
IBM email: neil_richards at uk.ibm.com
IBM United Kingdom Limited - Registered in England and Wales with number 741598.
Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6 3AU

More information about the jdk7u-dev mailing list