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

[Joe Darcy]

On 3/28/2022 9:08 AM, Alex Buckley wrote:
> 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"?
>
A package without a package-info file, but with classes or interfaces 
declared to be in that package.

-Joe