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

[Artem Ananiev]

On 9/17/2012 2:29 AM, David Holmes wrote:
> 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.

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.

Thanks,

Artem

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