RFR: 8336754: Remodel TypeAnnotation to "has" instead of "be" an Annotation [v7]

[Chen Liang]

On Thu, 1 Aug 2024 20:02:54 GMT, Chen Liang <liach at openjdk.org> wrote:

>> `TypeAnnotation` is not an annotation, as it should not be used in places like `AnnotationValue.ofAnnotation`. Thus it's remodeled to contain an annotation at a given location instead of to be an annotation.
>> 
>> Depends on #20205.
>
> Chen Liang has updated the pull request with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains 10 additional commits since the last revision:
> 
>  - Improve docs for repeating, default, and value name
>  - Merge branch 'master' of https://github.com/openjdk/jdk into fix/typeanno-model
>  - Merge branch 'master' of https://github.com/openjdk/jdk into fix/typeanno-model
>  - More refinements from alex
>  - Artifact -> construct
>  - More about Annotation, add equals note
>  - Further refine wording
>  - Refine the spec of TypeAnnotation per Alex feedback
>  - SealedGraph now redundant
>  - 8336754: Remodel TypeAnnotation to "has" instead of "be" an Annotation

I have implemented the suggestions (compiled to -> represented by, key-value -> element value) and tried to simplify the wording. Please review the current version:

 * <p>
 * In an annotation in Java source code, elements in the annotation interface
 * with default values may not be represented unless an explicit value is provided.
 * ({@jls 9.6.2}) The default value is derived from the {@link AnnotationDefaultAttribute
 * AnnotationDefault} attribute on the method representing the annotation
 * interface element, in the class file representing the annotation interface.
 * <p id="repeatable">
 * Multiple annotations of the same interface <i>A</i> in Java source code
 * ({@jls 9.7.5}) are represented by the {@linkplain AnnotationValue.OfAnnotation
 * annotation-valued} array elements of the {@linkplain AnnotationValue.OfArray
 * array-valued} element named {@code value} of a container annotation, whose
 * interface is the containing annotation interface of <i>A</i>. ({@jls 9.6.3})

// location in class files to source code construct/type section
 * If this annotation is of a {@linkplain ##repeatable repeatable} annotation
 * interface <i>A</i>, is an array element of an array-valued element named
 * {@code value} in a container annotation, and the interface of the container
 * annotation is the containing annotation interface <i>AC</i> of <i>A</i>,
 * this annotation represents a base annotation of type <i>A</i>, which applies
 * to the same source code construct or type as the container annotation of
 * type <i>AC</i>.

// On AnnotationElement::name
     * @apiNote
     * In Java source code, by convention, the name of the sole element in a
     * single-element annotation interface is {@code value}. ({@jls 9.6.1})
     * A single-element annotation ({@jls 9.7.3}) declares the element value
     * for the {@code value} element. The single element of a containing
     * annotation interface that holds {@linkplain Annotation##repeatable
     * multiple} base annotations is also named {@code value}. ({@jls 9.6.3})

-------------

PR Comment: https://git.openjdk.org/jdk/pull/20247#issuecomment-2264242499