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

[Martin Buchholz]

Tricky stuff!

---

We don't use closing html tags for things like <p> in javadoc.

---

+ * in concurrent contexts in which each instance of the annotated
+ * object is often accessed by a different thread.</p>

Hmmm...  makes it sound like it applies even if each instance is
thread-confined (in a different thread) or is immutable.  "objects" are not
annotated.

Maybe "instances of the annotated class are frequently accessed by multiple
threads and have fields that are frequently written".

---

Subclassing makes things tricky.  I think it would be pretty common to want
a subclass field to be in the same contention group as a superclass
contention group.


---

however, remain in force for all
+ * superclass and subclass instances


"remain in force for superclass instances" doesn't make sense to me.  Do
you mean "remain in force when fields are inherited in subclasses"

---

Do we want final fields to be explicitly exempt from being treated as
contended?  Or is that Quality of Implementation?  Do we want to insert the
word "non-final" in "all the unannotated fields"