From artem.ananiev at oracle.com Mon Sep 17 03:17:47 2012 From: artem.ananiev at oracle.com (Artem Ananiev) Date: Mon, 17 Sep 2012 14:17:47 +0400 Subject: [7u10] Request for approval: 7166055: Javadoc for WeakHashMap contains misleading advice In-Reply-To: <5056F765.9020207@oracle.com> References: <5052E346.7080107@linux.vnet.ibm.com> <505361E0.7060508@oracle.com> <50545C9E.4070507@oracle.com> <50549E28.9010700@oracle.com> <505652B0.9020203@oracle.com> <5056F4DF.1020003@oracle.com> <5056F765.9020207@oracle.com> Message-ID: <5056F8CB.9080901@oracle.com> (Adding conformance-discuss to CC) On 9/17/2012 2:11 PM, Alan Bateman wrote: > On 17/09/2012 11:01, Artem Ananiev wrote: >> >> JavaDoc changes, even trivial corrections and clarifications, are >> potential compatibility issues. Previously unverifiable statement can >> become verifiable, and vice versa. We don't (can't!) change >> compatibility tests in update releases, therefore we can't accept any >> specification changes. > The discussion here relates to changes to non-normative text rather than > a specification change. I don't think it matters too much if such > changes are back-ported except that it might be a bit confusing to have > a mismatch between the source code and the docs on java.sun.com (or > docs.orcale.com nowadays). The difference between "non-normative text" and "specification" is often too subtle, and people may have different opinion what is what. I personally don't have any better ideas than to prohibit any spec changes in update releases, but I don't want to pretend to be a compatibility expert. Thanks, Artem > -Alan From mike.duigou at oracle.com Mon Sep 17 12:47:27 2012 From: mike.duigou at oracle.com (Mike Duigou) Date: Mon, 17 Sep 2012 12:47:27 -0700 Subject: [7u10] Request for approval: 7166055: Javadoc for WeakHashMap contains misleading advice In-Reply-To: <5056F8CB.9080901@oracle.com> References: <5052E346.7080107@linux.vnet.ibm.com> <505361E0.7060508@oracle.com> <50545C9E.4070507@oracle.com> <50549E28.9010700@oracle.com> <505652B0.9020203@oracle.com> <5056F4DF.1020003@oracle.com> <5056F765.9020207@oracle.com> <5056F8CB.9080901@oracle.com> Message-ID: <4C965793-D8B1-4D96-AEE3-51A370947E26@oracle.com> Spec changes are already prohibited in update releases. If a documentation change implies a spec change then it's not allowed by our rules. This means though that it should be "safe" to update/republish the documentation with each update release. To me this seems like a good idea as it allows for incremental improvement without having to wait multiple years between major releases. I would gladly trade being able to make more frequent updates for additional caution in what changes we allow. Mike On Sep 17 2012, at 03:17 , Artem Ananiev wrote: > > (Adding conformance-discuss to CC) > > On 9/17/2012 2:11 PM, Alan Bateman wrote: >> On 17/09/2012 11:01, Artem Ananiev wrote: >>> >>> JavaDoc changes, even trivial corrections and clarifications, are >>> potential compatibility issues. Previously unverifiable statement can >>> become verifiable, and vice versa. We don't (can't!) change >>> compatibility tests in update releases, therefore we can't accept any >>> specification changes. >> The discussion here relates to changes to non-normative text rather than >> a specification change. I don't think it matters too much if such >> changes are back-ported except that it might be a bit confusing to have >> a mismatch between the source code and the docs on java.sun.com (or >> docs.orcale.com nowadays). > > The difference between "non-normative text" and "specification" is often too subtle, and people may have different opinion what is what. I personally don't have any better ideas than to prohibit any spec changes in update releases, but I don't want to pretend to be a compatibility expert. > > Thanks, > > Artem > >> -Alan From sean.coffey at oracle.com Tue Sep 18 10:30:09 2012 From: sean.coffey at oracle.com (=?UTF-8?B?U2XDoW4gQ29mZmV5?=) Date: Tue, 18 Sep 2012 18:30:09 +0100 Subject: [7u10] Request for approval: 7166055: Javadoc for WeakHashMap contains misleading advice In-Reply-To: <1176549880.1709680.1347979874332.JavaMail.root@redhat.com> References: <1176549880.1709680.1347979874332.JavaMail.root@redhat.com> Message-ID: <5058AFA1.7050500@oracle.com> 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 >>>>>> >>>>>> From joe.darcy at oracle.com Tue Sep 25 17:37:11 2012 From: joe.darcy at oracle.com (Joe Darcy) Date: Tue, 25 Sep 2012 17:37:11 -0700 Subject: [7u10] Request for approval: 7166055: Javadoc for WeakHashMap contains misleading advice In-Reply-To: <5058AFA1.7050500@oracle.com> References: <1176549880.1709680.1347979874332.JavaMail.root@redhat.com> <5058AFA1.7050500@oracle.com> Message-ID: <50624E37.4080303@oracle.com> 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 >>>>>>> >>>>>>> >>>>>>> > From sean.coffey at oracle.com Thu Sep 27 03:46:49 2012 From: sean.coffey at oracle.com (=?UTF-8?B?U2XDoW4gQ29mZmV5?=) Date: Thu, 27 Sep 2012 11:46:49 +0100 Subject: [7u10] Request for approval: 7166055: Javadoc for WeakHashMap contains misleading advice In-Reply-To: <50624E37.4080303@oracle.com> References: <1176549880.1709680.1347979874332.JavaMail.root@redhat.com> <5058AFA1.7050500@oracle.com> <50624E37.4080303@oracle.com> Message-ID: <50642E99.7020002@oracle.com> 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 >>>>>>>> >>>>>>>> >>>>>>>> >> > From joe.darcy at oracle.com Thu Sep 27 18:09:31 2012 From: joe.darcy at oracle.com (Joseph Darcy) Date: Thu, 27 Sep 2012 18:09:31 -0700 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: <5064F8CB.8070000@oracle.com> Hi Sean, On 9/27/2012 3:46 AM, 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 ? I'm happy to be asked for an opinion if the situation is unclear. FWIW, in the Java Language Specification for Java SE 7, the source document has labels for each sentance regarding whether or it normative or informative/commentary. In principle, the same sort of mark-up could be added to the javadoc of the Java SE APIs to indicate which text is part of the specification versus supporting text of some kind. However, I for one wouldn't be the first to sign up for the task of retrofitting the existing APIs in this way! Cheers, -Joe > > 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 >>>>>>>>> >>>>>>>>> >>>>>>>>> >>> >> >