Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

JDK-8283730: Improve discussion of modeling of packages and modules #7980

Closed
wants to merge 15 commits into from
+94 −15
Closed

JDK-8283730: Improve discussion of modeling of packages and modules #7980

Changes from 1 commit
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
f9bc1f8
JDK-8283730: Improve discussion of modeling of packages and modules
jddarcy Mar 27, 2022
1e7e774
Add links and fix typos.
jddarcy Mar 27, 2022
e26cff7
Fix more typos.
jddarcy Mar 27, 2022
640d6e8
Update package-info file.
jddarcy Mar 27, 2022
8892922
Various edits.
jddarcy Mar 28, 2022
109227d
Respond to review feedback.
jddarcy Mar 28, 2022
a5a2142
Merge branch 'master' into JDK-8283730
jddarcy Mar 28, 2022
4652121
Add discussion of automatic modules.
jddarcy Mar 28, 2022
c146bbc
Further refine discussion of ModuleElement.
jddarcy Mar 29, 2022
d1d9d8c
Merge branch 'master' into JDK-8283730
jddarcy Mar 31, 2022
d83c69d
Respond to review feedback.
jddarcy Apr 1, 2022
bc93fe1
Refine package description.
jddarcy Apr 2, 2022
a294451
Respond to more review feedback.
jddarcy Apr 2, 2022
63404c7
Merge branch 'master' into JDK-8283730
jddarcy Apr 5, 2022
08aaeec
Reflow paragraphs.
jddarcy Apr 5, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions src/java.compiler/share/classes/javax/lang/model/element/ModuleElement.java
View file
Original file line number Diff line number Diff line change
@@ -33,13 +33,13 @@
* information about the module, its directives, and its members.
*
* @apiNote
* The represented module may have an explicit source code or
* executable output {@linkplain
* The represented module may have an explicit {@linkplain
* javax.lang.model.util.Elements#getFileObjectOf(Element) backing
* construct} or may be created from implicit information. The
* explicit source code construct for a module is typically a {@code
* module-info.java} file (JLS {@jls 7.7}). Implicit information is
* used to model {@linkplain #isUnnamed unnamed modules}.
* construct} (either source code or executable output) or may be
* created from implicit information. The explicit source code
* construct for a module is typically a {@code module-info.java} file
* (JLS {@jls 7.7}). Implicit information is used to model {@linkplain
* #isUnnamed unnamed modules}.
*
* @see javax.lang.model.util.Elements#getModuleOf
* @since 9
14 changes: 7 additions & 7 deletions src/java.compiler/share/classes/javax/lang/model/element/PackageElement.java
View file
Original file line number Diff line number Diff line change
@@ -34,16 +34,16 @@
*
* @apiNote
* The represented package may have an explicit {@linkplain
* javax.lang.model.util.Elements#getFileObjectOf(Element) backing
* construct} (either {@linkplain
* javax.annotation.processing.Filer#createSourceFile(CharSequence,
* Element...) source code} or {@linkplain
* javax.annotation.processing.Filer#createClassFile(CharSequence,
* Element...) executable output} {@linkplain
* javax.lang.model.util.Elements#getFileObjectOf(Element) backing
* construct} or may be created from implicit information. The
* explicit source code construct for a package is typically a {@code
* package-info.java} file (JLS {@jls 7.4.1}). Implicit information is
* used to model {@linkplain #isUnnamed unnamed packages} as well as
* named packages without explicit declarations.
* Element...) executable output}) or may be created from implicit
* information. The explicit and standalone source code construct for
* a package is typically a {@code package-info.java} file (JLS {@jls
* 7.4.1}). Implicit information is used to model {@linkplain
* #isUnnamed unnamed packages}.
*
* @see javax.lang.model.util.Elements#getPackageOf
* @since 1.6
18 changes: 11 additions & 7 deletions src/java.compiler/share/classes/javax/lang/model/element/TypeElement.java
View file
Original file line number Diff line number Diff line change
@@ -54,19 +54,23 @@
* returned in source code order.
*
* @apiNote
* The represented class or interface may have an explicit {@linkplain
* The represented class or interface may have an explicit backing
* construct (either {@linkplain
* javax.annotation.processing.Filer#createSourceFile(CharSequence,
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Filer references here feel a bit weird. While most TypeElements 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 TypeElements with a backing construct are created via Filer.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In the latest pushed, pulled out the information specific to an annotation processing. New plain text:

ModuleElement:
"The represented module may have an explicit reference representation (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). Automatic modules (JLS 7.7.1) are named modules that do not have a module-info file. Implicit information is used to model unnamed modules.

In the context of annotation processing, a module element can be:

  • created from the initial inputs to a run of the tool

  • queried for in the configured environment

PackageElement
The represented package may have an explicit reference representation (either source code or executable output) or may be created from implicit information. The explicit and standalone 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.

In the context of annotation processing, a package element can be:

  • created from the initial inputs to a run of the tool

  • created from source code or class files written by a processor

  • queried for in the configured environment

TypeElement
The represented class or interface may have a reference representation (either source code or executable output). Multiple classes and interfaces can share the same reference representation 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

  •     a top-level class or interface and nested class and interfaces within it

    In the context of annotation processing, a type element can be:

  •     created from the initial inputs to a run of the tool

  •     created from source code or class files written by a processor

  •     queried for in the configured environment

* Element...) source code} or {@linkplain
* javax.annotation.processing.Filer#createClassFile(CharSequence,
* Element...) executable output} backing construct. Multiple classes
* and interfaces can share the same {@linkplain
* Element...) executable output}). Multiple classes and interfaces
* can share the same {@linkplain
* javax.lang.model.util.Elements#getFileObjectOf(Element) backing
* construct}. For example, multiple classes and interface can be
* declared in the same source file, including, but are not limited
* to, a {@linkplain NestingKind#TOP_LEVEL top-level} class or
* interface and auxiliary classes and interfaces or a top-level class
* or interface and {@linkplain NestingKind#isNested() nested classes}
* within it.
* to:
* <ul>
* <li> a {@linkplain NestingKind#TOP_LEVEL top-level} class or
* interface and auxiliary classes and interfaces
* <li>a top-level class or interface and {@linkplain
* NestingKind#isNested() nested class and interfaces} within it
* </ul>
*
* @see DeclaredType
* @since 1.6