(See JDK-8215035 and http://mail.openjdk.java.net/pipermail/compiler-dev/2018-December/012738.html )

## Overview:

4.7.20.2 discusses types that contain multiple parts on which annotations may appear, and describes "left-to-right step[s]" and annotations being "deeper" in nested or array types. There's an understanding here of the structure of a type and of positional relationships between parts of types (deeper and shallower, left and right) that could be made clearer. The linked thread discusses formalizing the idea of a "containment" relationship between types, and using that to clarify definition of the type_path structure.

## Background

Discussion of using the idea of a 'containment' relationship more generally (http://mail.openjdk.java.net/pipermail/compiler-dev/2018-December/012736.html):

"""
Words based on "inner" and "outer" connect most strongly with nested types, where the containment relation is clear from the declaration site. Still, I can imagine that "outermost part" could be ascribed meaning for a array type or a parameterized type, where the containment exists but is driven by the use site. For example, given a use of the type T[][], the outermost type is T[][] and the innermost type is T; given a use of the type A<B<C>>, the outermost type is A<..> and the innermost type is C. This would specify the meaning of a non-zero path_length more firmly than "... each entry in the path array represents an iterative, left-to-right step towards the precise location of the annotation in an array type, nested type, or parameterized type".
"""

Discussion of where the current left-to-right language is confusing (http://mail.openjdk.java.net/pipermail/compiler-dev/2018-December/012737.html):

"""
Assuming an example like 4.7.20.2-C, we step into the array type like so:

String [] [] []
       ^

String [] [] []
          ^

String [] [] []
             ^

String [] [] []
^

Thinking of that as "left-to-right" seems confusing.

It works better applied to the type descriptor, but the rest of 4.7.20.2 talks about types more abstractly.

[[[Ljava/lang/String;
^

[[[Ljava/lang/String;
 ^

[[[Ljava/lang/String;
  ^

[[[Ljava/lang/String;
   ^
"""

This presentation about "Enhanced Metadata in Java SE 8" (https://www.youtube.com/watch?v=Ri5D9oCwI2Q&t=41m) introduces an informal idea of containment, and discusses "zooming in" from a parameterized type to its type argument:

"""
First, get the field declaration:

+--------------------------+
| List<@NonNull String> f; |
+--------------------------+

Second, get the field's type:

+-----------------------+
| List<@NonNull String> | f;
+-----------------------+

Finally, zoom in to the type arguments:

      +-----------------+
List< | @NonNull String | >
      +-----------------+
"""

## Sketch of proposed language

Containment is a binary relation on types.

A type is said to contain the types obtained by transitive closure over the direct containment relation.

* Given a nested type `T.C`, the enclosing type `T` directly contains the nested type `C`.
* An array type `T[]` directly contains its component type `T`.
* A bounded wildcard type `? extends T` or `? super T` directly contains its bound `T`.
* A parameterized type `C<T1,...,Tn>` directly contains all of its type arguments `T1,...,Tn`.

The value of the path_length item gives the number of entries in the path array:

* If the value of path_length is 0, then the annotation applies to the outermost containing type for which a type annotation is admissible.
* If the value of path_length is non-zero, then each entry in the path array represents a step from a containing type to a directly contained type, towards the precise location of the annotation.

type_path_kind

The legal values for the type_path_kind item are listed in Table 4.7.20.2-A.

Table 4.7.20.2-A. Interpretation of type_path_kind values

The annotation is associated with a type contained by...

* 0: an array type
* 1: a nested type
* 2: a bounded wildcard type
* 3: a parameterized type