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

[David Holmes]

Hi Aleksey,

Okay I have some suggested rewordings below and a couple of grammatical 
corrections.

I've trimmed out parts that are unchanged.

On 27/05/2013 10:44 PM, Aleksey Shipilev wrote:
> A {@code @Contended} field annotation may optionally include a
> contention group tag. All fields with the same tag are considered as a
> group with respect to isolation from other groups. A default tag
> indicates the <i>distinct</i> and <i>anonymous</i> contention group,
> which implies the contention with all other fields, including all other
> {@code @Contended} ones. The tag at a class level is meaningless, and
> ignored.

A {@code @Contended} field annotation may optionally include a 
<i>contention group</i> tag. A contention group defines a set of one or 
more fields that collectively must be isolated from all other contention 
groups. With no contention group tag (or with the default empty tag: "") 
each {@code @Contended} field resides in its own <i>distinct</i> and 
<i>anonymous</i> contention group. A contention group tag has no meaning 
in a class level {@code @Contended} annotation, and is ignored.

> ... With the class level annotation, the implementations may
> choose different approach to protect the entire object, rather
> than protecting only the distinct fields.

With the class level annotation, implementations may choose different 
isolation techniques, such as isolating the entire object, rather than 
isolating distinct fields.

> The {@code @Contended} annotation is not inherited, and acts only
> within the class it was used on. The effects, however, should be
> enforced across the inheritance, e.g. the {@code @Contended} fields
> should be isolated from all the fields in super- and sub-classes. The
> contention group tags are not inherited as well: the similar tags in two
> subclasses mean different groups.

The class level {@code @Contended} annotation is not inherited and has 
no effect on the fields of any sub-classes. The effects of all {@code 
@Contended} annotations, however, remain in force for all subclass 
instances, providing isolation of all the defined contention groups. 
Contention group tags are not inherited, and the same tag used in a 
superclass and subclass, represent distinct contention groups.

>       * The (optional) contention group tag.
>       * This tag is only meaningful for the field-level annotations.

Delete "the" in "for the".

Check "field-level" vs. "field level" usage; and "class-level" vs "class 
level" usage. I'm not sure what the JDK conventions are so you may need 
to find other examples. Just be sure to be internally consistent if 
there is no clear convention.

Thanks,
David
------