Thanks Stephen,
I am fine with your wording. Any other votes or suggested wordings?
Mike
On Aug 28 2013, at 02:55 , Stephen Colebourne wrote:
> I lke the idea, but the wording feels a little opaque as the result is
> typically StackOverflow.
>
> Also, I prefer a style with the @apiNote on a line of its own, rather
> like a heading. It makes the documentation easier to read in source
> code, and has no effect on the output Javadoc.
>
> @apiNote
> If the Collection is self-referential, where it directly or indirectly
> contains itself, then the calculation of hashCode may fail with an
> exception. Implementations may optionally try to handle this scenario,
> however most current implementations do not do so.
>
> Stephen
>
> On 28 August 2013 03:06, Mike Duigou <mike.dui...@oracle.com> wrote:
>> Hello all;
>>
>> Fairly frequently it is reported that various Collection/Map implementations
>> of hashCode() fail when the instance directly or indirectly contains itself.
>> For a variety of reasons, mostly performance and resource related, most
>> implementations choose not to support calculation of hash codes for
>> self-referential collections. This is not likely to change. So to reduce
>> confusion and "bug" reports I am proposing a non-normative @apiNote be added
>> to Collection and HashMap. The text of the proposed note is:
>>
>>> Support for calculation of hash code by self referential {Collection|Map}s
>>> (they either directly or indirectly contain themselves) is optional. Few
>>> Collection implementations support calculation of hash code for self
>>> referential instances.
>>
>>
>> http://cr.openjdk.java.net/~mduigou/JDK-7057785/0/webrev/
>>
>> Cheers,
>>
>> Mike
