RFR : 8008632 : Additional JavaDoc tags @apiNote, @implSpec and @implNote for JDK API Docs

[Martin Buchholz]

On Mon, Dec 9, 2013 at 3:58 PM, Mike Duigou <mike.duigou at oracle.com> wrote:

>
> While the tags themselves are private, their output is not.  When users
> read:
>
> Implementation Requirements:
>
>
> This is still changeable. "Required behaviour of all implementations:"
> perhaps?
>
>
I think this is not moving us towards clarity.   "Required behaviour of all
implementations:" actually applies more to the "regular" unlabelled
documentation, since that applies to subclasses as well.  Perhaps we want
to get rid of words like "requirements" because they apply equally to the
part not labelled "requirements"?!  The key difference is that we are
documenting the behavior of THIS method on THIS class.  Maybe:

Behavior of the default method Map.forEach:

When I was musing about doing this myself years ago, I was not motivated by
default methods (they didn't exist yet!) but instead by the "skeletal"
implementation classes like AbstractMap.  Hopefully we can @implSpec them
for jdk8?