JDK 14 RFR of JDK-8230337: Clarify intention of Elements.{getPackageOf, getModuleOf}

[Joe Darcy]

Hello,

Responding to some off-list comments from Jon, please review the 
proposed spec changes for

     JDK-8230337: Clarify intention of Elements.{getPackageOf, getModuleOf}
     CSR: https://bugs.openjdk.java.net/browse/JDK-8230357
     webrev: http://cr.openjdk.java.net/~darcy/8230337.0/

Diff with below. A summary of the change is to formalize the informal 
(and implicit) "enclosing package" and "enclosing module" relationship.

Once the wording is finalized, I'll review the tests of this area.

Thanks,

-Joe

@@ -451,14 +451,19 @@
      /**
       * Returns the package of an element.  The package of a package is
       * itself.
       * The package of a module is {@code null}.
       *
-     * @param type the element being examined
+     * The package of a top-level type is its {@linkplain
+     * TypeElement#getEnclosingElement enclosing package}. Otherwise,
+     * the package of an element is equal to the package of the
+     * {@linkplain Element#getEnclosingElement enclosing element}.
+     *
+     * @param e the element being examined
       * @return the package of an element
       */
-    PackageElement getPackageOf(Element type);
+    PackageElement getPackageOf(Element e);

      /**
       * Returns the module of an element.  The module of a module is
       * itself.
       * If there is no module for the element, null is returned. One 
situation where there is

@@ -466,19 +471,25 @@
       * an annotation processing environment configured for
       * a {@linkplain
       * javax.annotation.processing.ProcessingEnvironment#getSourceVersion
       * source version} without modules.
       *
+     * If a package has a module as its {@linkplain
+     * PackageElement#getEnclosingElement enclosing element}, that
+     * module is the module of the package. Otherwise, the module of
+     * an element is equal to the module {@linkplain
+     * #getPackageOf(Element) of the package} of the element.
+     *
       * @implSpec The default implementation of this method returns
       * {@code null}.
       *
-     * @param type the element being examined
+     * @param e the element being examined
       * @return the module of an element
       * @since 9
       * @spec JPMS
       */
-    default ModuleElement getModuleOf(Element type) {
+    default ModuleElement getModuleOf(Element e) {
          return null;
      }

      /**
       * Returns all members of a type element, whether inherited or