JDK 13 RFR of JDK-8225495: "Note whether returned annotations are declaration annotations or type annotations."

[Alex Buckley]

On 6/9/2019 5:03 PM, Joe Darcy wrote:
> Please review the changes to address:
>
>      JDK-8225495: "Note whether returned annotations are declaration
> annotations or type annotations."
>      webrev: http://cr.openjdk.java.net/~darcy/8225495.0/
>      specdiff:
> http://cr.openjdk.java.net/~darcy/8225495.0.specdiff/overview-summary.html
>
> Conceptually, the change is just to add
>
>      "Note that any annotations returned by this method are
> (declaration|type) annotations."
>
> to the appropriate methods, three for element modeling hierarchy and
> three for the type modeling hierarchy. This requires adding various
> method overrides to host the specialized javadoc.

Adding all these method specs to call out "declaration annotations" or 
"type annotations" seems (1) a bit clunky, and (2) a bit hopeful given 
that neither term is defined in jx.l.m.AnnotatedConstruct, Element, 
TypeMirror. Recommend an upgrade to jx.l.m.AnnotatedConstruct:

-----
Represents a construct that can be annotated. ~~A construct is either an 
element or a type. Annotations on an element are on a declaration, 
whereas annotations on a type are on a specific use of a type name.~~ 
++A CONSTRUCT IS EITHER AN _ELEMENT_, REPRESENTING A DECLARATION IN A 
PROGRAM, OR A _TYPE_, REPRESENTING A SPECIFIC USE OF A TYPE WITHIN A 
DECLARATION, STATEMENT, OR EXPRESSION IN A PROGRAM.++  [I WAS GOING TO 
SAY "IN SOURCE CODE", THEN I RECALLED JEP 119 AND HOW JX.L.M IS NOT 
LIMITED TO MODELING SOURCE STRUCTURES.]  ++AN ELEMENT EXPOSES THE 
ANNOTATIONS THAT APPEAR ON A DECLARATION IN A PROGRAM, KNOWN AS 
_DECLARATION ANNOTATIONS_. A TYPE EXPOSES THE ANNOTATIONS THAT APPEAR ON 
A SPECIFIC USE OF A TYPE IN A PROGRAM, KNOWN AS _TYPE ANNOTATIONS_.++

The terms ... are used throughout this interface to describe precisely 
which annotations ++(WHETHER DECLARATION ANNOTATIONS OR TYPE 
ANNOTATIONS)++ are returned by the methods ~~defined herein~~ ++OF THIS 
INTERFACE.++  [PULL THE FOLLOWING INTO THIS PARA.]  In the definitions 
below, an annotation A has an annotation type AT; IF AT is a repeatable 
annotation type, THEN the type of the containing annotation is ATC.

Annotation A is directly present on a construct C if either:
-----

In what follows, the phrases "explicitly declared" and "implicitly 
declared" appear. These are JLS terms that don't work well once we 
highlight "declaration annotations" in this interface spec. Thankfully, 
they only appear in the "directly present" definition; all further 
definitions are careful to vector through it. Here is the original text, 
with further comments after it:

-----
- A is explicitly or implicitly declared as applying to the source code 
representation of C.

Typically, if exactly one annotation of type AT appears in the source 
code of representation of C, then A is explicitly declared as applying 
to C. If there are multiple annotations of type AT present on C, then if 
AT is repeatable annotation type, an annotation of type ATC is 
implicitly declared on C.
-----

1. "source code representation"? Not "representation in a program"?

2. "A is explicitly declared on C", sure. "A is implicitly declared on 
C", huh? The point of jx.l.m.AnnotatedConstruct is to align with 
j.l.r.AnnotatedElement, where the directly-present case is uninterested 
in container annotations. And consider this: "A is ... implicitly 
declared" doesn't connect with "...an annotation of type ATC is 
implicitly declared", A isn't of type ATC.

The formatting of the four definitions is painful. Please add newlines, 
and use bold+italics on these words:

either:
either:
both:
either:

Add:

@jls 9.7.4 Where Annotations May Appear
@jls 9.7.5 Multiple Annotations of the Same Type

Finally, the interface specs for Element and TypeMirror are ready to 
refer to declaration annotations and type annotations:

- Element:  Represents a ~~program element~~ ["A FOO REPRESENTS A FOO" 
IS NOT ADDING ANY MEANING] ++DECLARATION IN A JAVA PROGRAM++, such as a 
module, package, class, method, OR VARIABLE. Each element represents a 
static, language-level construct, RATHER THAN a runtime construct of the 
~~virtual machine~~ ++JAVA VIRTUAL MACHINE WITH CAPITAL J V M++.  [I 
DON'T KNOW HOW TO INTERPRET THE PRECEDING SENTENCE WHEN CLASS FILE 
CONTENT IS EXPOSED VIA THIS API.]  ++THE METHODS INHERITED FROM 
ANNOTATEDCONSTRUCT EXPOSE ANY DECLARATION ANNOTATIONS THAT APPEAR ON 
THIS DECLARATION.++

- Type: ... first paragraph ... ++THE METHODS INHERITED FROM 
ANNOTATEDCONSTRUCT EXPOSE ANY TYPE ANNOTATIONS THAT APPEAR ON THE 
SPECIFIC USE OF A TYPE MODELED BY THIS TYPEMIRROR OBJECT.++  [YUK. THE 
PROBLEM IS THAT "REPRESENTS TYPES IN THE JAVA PROGRAMMING LANGUAGE." 
DOESN'T GET TO THE HEART OF "THIS MIRROR REPRESENTS A SPECIFIC UTTERANCE 
OF A TYPE AT SOME POINT IN THE PROGRAM."]

Alex