RFR: JDK-8281169: Expand discussion of elements and types

[Maurizio Cimadamore]

On Tue, 1 Aug 2023 05:00:23 GMT, Joe Darcy <darcy at openjdk.org> wrote:

> The goal is this change is to convey to the reader an accurate "vibe" for the dichotomy between elements and type in the javax.lang.model API rather than a primer on category theory (projection-embedding pairs, etc.).

I agree that a discussion on the distinction between types and elements is worthwhile. That said, in its current form the text, with its focus on annotations/type annotations, seems an attempts to show as to why j.l.m is better than core reflection, which I'm sure was not the intended goal. I'm not even sure that using annotations is a good example of this, given there is an example that Java developers probably see on a daily basis: generics. E.g. there is only one `ArrayList` class declararation, but there are *many* way to use that declaration (e.g. `ArrayList<String>`, `ArrayList<Number>`, `ArrayList<List<String>>` ...).

One key fact the reader should go away with is that declarations are typically reused - e.g. every use of ArrayList<X> (a type mirror), no matter the shape of its type arguments, will end up pointing at the "one and true" ArrayList declaration (an element). Perhaps it would be useful here to refer to concepts such as symbol tables, which are fairly common in compiler design.

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

PR Review: https://git.openjdk.org/jdk/pull/15097#pullrequestreview-1556568994