From neil.richards at ngmr.net Tue Oct 16 09:32:23 2012 From: neil.richards at ngmr.net (Neil Richards) Date: Tue, 16 Oct 2012 17:32:23 +0100 Subject: [7u10] Request for approval: 7166055: Javadoc for WeakHashMap contains misleading advice In-Reply-To: <50642E99.7020002@oracle.com> References: <1176549880.1709680.1347979874332.JavaMail.root@redhat.com> <5058AFA1.7050500@oracle.com> <50624E37.4080303@oracle.com> <50642E99.7020002@oracle.com> Message-ID: <1350405143.15426.2.camel@chalkhill> 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 > >>> 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