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

[Joe Darcy]

On Tue, 1 Aug 2023 11:08:56 GMT, Pavel Rappo <prappo 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

Thanks for the feedback; I'll mull over how to reformulate the discussion.

I'll state my intentions more explicitly in hopes of distilling more effective examples. One point in explaining elements vs types is delineating the distinction uses and definitions, "def-use" being another concept common in compilers. I intended the type annotation example to help motivate the distinction: "something" must encapsulate the difference between String with one set of annotations as a return type and String with a different set of annotations as the parameter type.

It would be technically possible to embed all the shared element/definition information into the type mirrors, but that would not be well-factored OO code.

I agree a generics example is a good one, which is why I included an abbreviated version of that in the "Mapping" discussion.

With the benefit of hindsight, as detailed in the "Mirror" paper cited earlier in the package-info file, core reflection has multiple design issues we were trying to do differently in the javax.lang.model API.

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

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