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
