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

[Mike Duigou]

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