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</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
