[7u10] Request for approval: 7166055: Javadoc for WeakHashMap contains misleading advice (original) (raw)

Mike Duigou mike.duigou at oracle.com
Mon Sep 17 12:47:27 PDT 2012

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

More information about the jdk7u-dev mailing list