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

[Joseph D. Darcy]

On 3/29/2022 9:18 AM, Alex Buckley wrote:
> On 3/28/2022 6:30 PM, Joseph D. Darcy wrote:
>> Okay; I added the "standalone" adjective to describe module-info 
>> file, paralleling the wording used to describe package-info and added 
>> "[implicit information] may be used" for for automatic modules:
>>
>> "The represented module 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 module is typically a module-info.java file (JLS 
>> 7.7). Implicit information is used to model unnamed modules and may 
>> be used for automatic modules (JLS 7.7.1)."
>>
>> (I think an explicit module-info.java file has a different degree of 
>> explicitness than an Automatic-Module-Name attribute, but don't think 
>> describing possibilities of Automatic-Module-Name attributes would be 
>> helpful in this context.)
>
> As a reader, I can't tell if an automatic module is going to be 
> exposed as a ModuleElement, and if it is, where the name is going to 
> originate. In other words, saying that _implicit_ info _may_ be used 
> to model a first-class platform concept is too weak IMO.
>
In the full javadoc rendering of the text in question, "automatic 
modules" in "Implicit information is used to model unnamed modules and 
may be used for automatic modules..." is a link to the utility method 
javax.lang.model.util.Elements.isAutomaticModule, from which reader 
could infer that a full implementation of the language model includes 
support for automatic modules.

Consistent with other aspect of the design of javax.lang.model, there 
are not explicit statements along the lines of "If the backing store is 
a class file, then the return value of method Foo is constructed from 
class file (or jar file) binary attribute Bar under the following 
transformation..." Rather the background statement from the 
javax.lang.model.element package

     "When used in the context of annotation processing, an accurate 
model of the element being represented must be returned."

is used to guide general expectations.

-Joe