8283730: Improve discussion of modeling of packages and modules

Reviewed-by: jjg, jlahoda

src/java.compiler/share/classes/javax/annotation/processing/Filer.java

@@ -135,6 +135,9 @@ import java.io.IOException;
  * @since 1.6
  */
 public interface Filer {
+    // Maintenance note: if the ability to create module-info files
+    // through the Filer is added, add link to this method from
+    // ModuleElement interface-level discussion.
     /**
      * Creates a new source file and returns an object to allow
      * writing to it. A source file for a class, interface, or a
@@ -217,6 +220,9 @@ public interface Filer {
     JavaFileObject createSourceFile(CharSequence name,
                                     Element... originatingElements) throws IOException;
 
+    // Maintenance note: if the ability to create module-info files
+    // through the Filer is added, add link to this method from
+    // ModuleElement interface-level discussion.
     /**
      * Creates a new class file, and returns an object to allow
      * writing to it. A class file for a class, interface, or a package can

src/java.compiler/share/classes/javax/lang/model/element/ModuleElement.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2020, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2022, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -32,6 +32,25 @@ import javax.lang.model.type.TypeMirror;
  * Represents a module program element.  Provides access to
  * information about the module, its directives, and its members.
  *
+ * @apiNote
+ * The represented module may have an explicit {@linkplain
+ * javax.lang.model.util.Elements#getFileObjectOf(Element) 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 {@code
+ * module-info.java} file (JLS {@jls 7.7}). {@linkplain
+ * javax.lang.model.util.Elements#isAutomaticModule(ModuleElement)
+ * Automatic modules} (JLS {@jls 7.7.1}) are named modules that do
+ * <em>not</em> have a {@code module-info} file. Implicit information
+ * is used to model {@linkplain #isUnnamed unnamed modules}.
+ * <p>In the context of annotation processing, a module element can
+ * be:
+ * <ul>
+ * <li>created from the initial inputs to a run of the tool
+ * <li>{@linkplain javax.lang.model.util.Elements#getModuleElement(CharSequence)
+ * queried for} in the configured environment
+ * </ul>
+ *
  * @see javax.lang.model.util.Elements#getModuleOf
  * @since 9
  * @jls 7.7 Module Declarations

src/java.compiler/share/classes/javax/lang/model/element/PackageElement.java

@@ -32,6 +32,31 @@ import javax.lang.model.type.TypeMirror;
  * Represents a package program element.  Provides access to information
  * about the package and its members.
  *
+ * @apiNote
+ * The represented package may have an explicit {@linkplain
+ * javax.lang.model.util.Elements#getFileObjectOf(Element) 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 {@code
+ * package-info.java} file (JLS {@jls 7.4.1}).  A named package
+ * without a standalone {@code package-info.java} file can be declared
+ * in the package declaration of a {@linkplain NestingKind#TOP_LEVEL
+ * top-level} class or interface.  Implicit information is used to
+ * model {@linkplain #isUnnamed unnamed packages} (JLS {@jls 7.4.2}).
+ * <p>In the context of annotation processing, a package element can
+ * be:
+ * <ul>
+ * <li>created from the initial inputs to a run of the tool
+ * <li>created from {@linkplain
+ * javax.annotation.processing.Filer#createSourceFile(CharSequence,
+ * Element...) source code} or {@linkplain
+ * javax.annotation.processing.Filer#createClassFile(CharSequence,
+ * Element...) class files} written by a processor
+ * <li>{@linkplain
+ * javax.lang.model.util.Elements#getAllPackageElements(CharSequence)
+ * queried for} in the configured environment
+ * </ul>
+ *
  * @see javax.lang.model.util.Elements#getPackageOf
  * @since 1.6
  */

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

@@ -53,6 +53,33 @@ import javax.lang.model.util.*;
  * source of information is Java source code, then the elements will be
  * returned in source code order.
  *
+ * @apiNote
+ * The represented class or interface may have a {@linkplain
+ * javax.lang.model.util.Elements#getFileObjectOf(Element) 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:
+ * <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>
+ * <p>In the context of annotation processing, a type element can
+ * be:
+ * <ul>
+ * <li>created from the initial inputs to a run of the tool
+ * <li>created from {@linkplain
+ * javax.annotation.processing.Filer#createSourceFile(CharSequence,
+ * Element...) source code} or {@linkplain
+ * javax.annotation.processing.Filer#createClassFile(CharSequence,
+ * Element...) class files} written by a processor
+ * <li>{@linkplain
+ * javax.lang.model.util.Elements#getAllTypeElements(CharSequence)
+ * queried for} in the configured environment
+ * </ul>
  * @see DeclaredType
  * @since 1.6
  */

src/java.compiler/share/classes/javax/lang/model/element/package-info.java

@@ -63,7 +63,8 @@
  * <ul>
  * <li> {@code strictfp} on a class or interface
  * <li> {@code final} on a parameter
- * <li> {@code protected}, {@code private}, and {@code static} on classes and interfaces
+ * <li> {@code protected}, {@code private}, and {@code static} on
+ *      classes and interfaces
  * </ul>
  *
  * Some elements which are {@linkplain
@@ -86,19 +87,20 @@
  * code is not syntactically well-formed or has some other
  * irrecoverable error that could not be removed by the generation of
  * new classes or interfaces, a model may or may not be provided as a
- * quality of implementation issue.  If a program is syntactically
- * valid but erroneous in some other fashion, any returned model must
- * have no less information than if all the method bodies in the
- * program were replaced by {@code "throw new RuntimeException();"}.
- * If a program refers to a missing class or interface Xyz, the
- * returned model must contain no less information than if the
- * declaration of class or interface Xyz were assumed to be {@code
- * "class Xyz {}"}, {@code "interface Xyz {}"}, {@code "enum Xyz {}"},
- * {@code "@interface Xyz {}"}, or {@code "record Xyz {}"}. If a
- * program refers to a missing class or interface {@code Xyz<K1,
- * ... ,Kn>}, the returned model must contain no less information than
- * if the declaration of Xyz were assumed to be {@code "class Xyz<T1,
- * ... ,Tn> {}"} or {@code "interface Xyz<T1, ... ,Tn> {}"}
+ * quality of implementation issue.  If a program for a class or
+ * interface is syntactically valid but erroneous in some other
+ * fashion, any returned model must have no less information than if
+ * all the method bodies in the program were replaced by {@code "throw
+ * new RuntimeException();"}.  If a program refers to a missing class
+ * or interface Xyz, the returned model must contain no less
+ * information than if the declaration of class or interface Xyz were
+ * assumed to be {@code "class Xyz {}"}, {@code "interface Xyz {}"},
+ * {@code "enum Xyz {}"}, {@code "@interface Xyz {}"}, or {@code
+ * "record Xyz {}"}. If a program refers to a missing class or
+ * interface {@code Xyz<K1, ... ,Kn>}, the returned model must contain
+ * no less information than if the declaration of Xyz were assumed to
+ * be {@code "class Xyz<T1, ... ,Tn> {}"} or {@code "interface Xyz<T1,
+ * ... ,Tn> {}"}
  *
  * <p> Unless otherwise specified in a particular implementation, the
  * collections returned by methods in this package should be expected