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

[Jan Lahoda]

On Tue, 29 Mar 2022 01:30:30 GMT, Joe Darcy <darcy at openjdk.org> wrote:

>> Informative update explicitly linking PackageElement objects to package-info.java files and ModuleElement objects to module-info.java files.
>> 
>> I'll reflow the updated paragraph in javax.lang.model.element.package-info before pushing.
>> 
>> 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.
>> 
>> 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.
>> 
>> Plain text update to TypeElement (added for symmetry with above updates):
>> 
>> The represented class or interface may have an explicit source code or executable output backing construct. 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 or a top-level class or interface and nested classes within it.
>
> Joe Darcy has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Further refine discussion of ModuleElement.

src/java.compiler/share/classes/javax/lang/model/element/TypeElement.java line 59:

> 57:  * The represented class or interface may have an explicit backing
> 58:  * construct (either {@linkplain
> 59:  * javax.annotation.processing.Filer#createSourceFile(CharSequence,

The `Filer` references here feel a bit weird. While most `TypeElement`s presumably have an explicit backing construct (i.e. a file), I suspect that only minority of the backing constructs are created using a `Filer`, but the text suggests(?) that all `TypeElement`s with a backing construct are created via `Filer`.

-------------

PR: https://git.openjdk.java.net/jdk/pull/7980