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

[Alex Buckley]

On 3/27/2022 8:57 PM, Joe Darcy wrote:
> Plain text update to PackageElement:
> 
> The represented package may have an explicit source code or executable output backing construct or may be created from implicit information. The explicit 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 as well as named packages without explicit declarations.

For readability, prefer "may have an explicit backing construct (either 
source code or executable output) or may be created from implicit ...".

The word "output" is a little strange in this context, since we're not 
discussing a compiler. You wouldn't look at a class file on a production 
system and call it "executable _output_". Alternative phrasing: "(in 
either source or binary form)" or "(either source code or a class file)".

> Plain text update to ModuleElement:
> 
> The represented module may have an explicit source code or executable output backing construct 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.

Just as PackageElement spoke of "named packages without explicit 
declarations", ModuleElement should appeal to the same idea: "... to 
model unnamed modules and automatic modules".

(Background info: JLS 7.7.1 notes that "The Java SE Platform 
distinguishes between named modules that are explicitly declared (that 
is, with a module declaration) and named modules that are implicitly 
declared (that is, automatic modules)." The specific platform spec where 
automatic modules are first class is java.lang.module.ModuleFinder::of.)

Wait, what are "named packages without explicit declarations"?

Alex