RFR (S) CR 8014966: Add the proper Javadoc to @Contended

[Aleksey Shipilev]

Thanks Mike!

The updated webrev is here:
  http://cr.openjdk.java.net/~shade/8014966/webrev.04/

I think the changes we are doing now are converging. I would like to
hear formal OKs from Martin B, Mike D, David H, so we can proceed with
pushing this. Last-minute grammar corrections welcome!

-Aleksey.

Summary of changes below:

On 05/31/2013 03:04 AM, Mike Duigou wrote:
> Since the statements are grouped by fields and classes, move this to
> the classes paragraph:
> 
> "A contention + * group tag has no meaning in a class level {@code
> @Contended} annotation, + * and is ignored."

Moved.

> Describing the behaviour of the class annotation by referencing
> unavailable functionality seems strange:
> 
> "the effect is + * roughly equivalent to placing the {@code
> @Contended} annotation + * with the <i>same</i> anonymous tag over
> all the unannotated fields of + * the object."
> 
> The reader is left wondering "how would I annotate multiple fields
> with the same anonymous tag?" Perhaps a statement in the fields
> paragraph that "To put multiple fields into the same anonymous group
> use the class level @C annotation".

Good point, rephrased to:
 * When the annotation is used at the class level, the effect is
 * equivalent to grouping all the fields not already having the
 * {@code @Contended} annotation into the same anonymous group.


> "over all the unannotated fields of + * the object."
> 
> This refers, of course, to fields without their own @C annotation not
> fields without annotations.

Yes, that is fixed as the side-effect of the change above.

> Addition:
> 
> <p>The class level {@code @Contended} annotation is not inherited and
> has + * no effect on the fields [defined] in any sub-classes.

Done. I think "declared" is the more applicable in Java world.

> Addition:
> 
> "The effects of all + * {@code @Contended} annotations [upon layout
> of object fields] remain in force for all"
> 

I am reluctant to add this, because mentioning field layout seems to
mean the particular implementation choice (which limits us from, say,
aligning the objects for the cache line).

> As I told Brian during the lambda javadoc efforts, writing 
> specification is the best kind of task--demanding, exacting and 
> tedious! :-)

Yeah. There is still some time before release, and lots of space on
cr.openjdk.java.net for the webrevs!