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

[Pavel Rappo]

On Tue, 1 Aug 2023 09:35:20 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

> 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

The proposed text reads well from the perspective of API design: that is, why separate interfaces for "use" and "definition" model this particular domain better. While such a perspective has its place, IMO it shouldn't be the primary perspective of that text.
 
> One key fact the reader should go away with is that declarations are typically reused - e.g. every use of ArrayList (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.

Perhaps the following issue could also be worked into this PR: https://bugs.openjdk.org/browse/JDK-8309666

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

PR Comment: https://git.openjdk.org/jdk/pull/15097#issuecomment-1660097564