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

[Alex Buckley]

On 3/30/2022 6:49 PM, Joseph D. Darcy wrote:
> On 3/29/2022 9:18 AM, Alex Buckley wrote:
>> On 3/28/2022 6:30 PM, Joseph D. Darcy wrote:
>>> "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)."
> 
> In the full javadoc rendering of the text in question, "automatic 
> modules" ... is a link to the utility method
> javax.lang.model.util.Elements.isAutomaticModule, from which reader
> could infer that ...
> 
> Consistent with other aspect of the design of javax.lang.model, ...

OK. However, I have strong reservations about whether the subclause "and
standalone" is effective at communicating what we want. The factoring is
not quite right -- a better factoring would be "The explicit source code
construct for a module is typically a standalone module-info.java file".
And for PackageElement: "The explicit source code construct for a 
package is typically a standalone package-info.java file."

Alex