RFR: JDK-8283730: Improve discussion of modeling of packages and modules

[Joseph D. Darcy]

On 3/28/2022 10:06 AM, Alex Buckley wrote:
> On 3/28/2022 9:50 AM, Joe Darcy wrote:
>> On 3/28/2022 9:08 AM, Alex Buckley wrote:
>>> Wait, what are "named packages without explicit declarations"?
>>>
>> A package without a package-info file, but with classes or interfaces 
>> declared to be in that package.
>
> Those classes and interfaces are thus declared in a compilation unit 
> _that also contains a package declaration_. `package p;` is a 
> first-class, full-strength, 100%-explicit package declaration whether 
> it appears in Foo.java or package-info.java. I think the Language 
> Model API is seeking the idea of "a named package with a _standalone_ 
> declaration, i.e., the package declaration occurs in an otherwise 
> empty compilation unit. Typically, this package declaration occurs in 
> a source file called package-info.java."

Plain text of review apiNotes:

PackageElement

The represented package may have an explicit backing construct (either 
source code or executable output) or may be created from implicit 
information. The explicit and standalone source code construct for a 
package is typically a package-info.java file (JLS 7.4.1). Implicit 
information is used to model unnamed packages.

ModuleElement

The represented module may have an explicit backing construct (either 
source code or executable output) or may be created from implicit 
information. The explicit source code construct for a module is 
typically a module-info.java file (JLS 7.7). Implicit information is 
used to model unnamed modules.

TypeElement

The represented class or interface may have an explicit backing 
construct (either source code or executable output). Multiple classes 
and interfaces can share the same backing construct. For example, 
multiple classes and interface can be declared in the same source file, 
including, but are not limited to:

     a top-level class or interface and auxiliary classes and interfaces
     a top-level class or interface and nested class and interfaces 
within it

Thanks,

-Joe