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

[Joe Darcy]

> 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:

  Respond to review feedback.

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

Changes:
  - all: https://git.openjdk.java.net/jdk/pull/7980/files
  - new: https://git.openjdk.java.net/jdk/pull/7980/files/8892922f..109227de

Webrevs:
 - full: https://webrevs.openjdk.java.net/?repo=jdk&pr=7980&range=01
 - incr: https://webrevs.openjdk.java.net/?repo=jdk&pr=7980&range=00-01

  Stats: 27 lines in 3 files changed: 7 ins; 3 del; 17 mod
  Patch: https://git.openjdk.java.net/jdk/pull/7980.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/7980/head:pull/7980

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