ModuleElement#getEnclosedElements() is underdocumented

[Jayaprakash Artanareeswaran]

Hello,


There's very little documentation on the newly added API - javax.lang.model.element.ModuleElement.getEnclosedElements(). All it says is this:


  "Returns the packages within this module."


Specifically, it doesn't mention when a package is considered to be enclosed in a module. For e.g., consider this case, where a Java module contains and exports a package with a single CU that has nothing but a package declaration statement.


module.one
  package.one
    package.one.one
      CU.java
        --
        // Nothing but a package declaration
        package package.one.one;
        --

Now during compilation of these sources, calling getEnclosedElements() on "module.one" returns a list that contains "package.one.one". So far so good. But compilation doesn't produce any .class files nor does it create a folder for "package.one.one". If you invoke the compiler again with the binaries and call getEnclosedElements(), Javac returns a list identical to our first iteration. Consistent alright, but in binary form, the package "package.one.one" doesn't point to any physical location nor does it contain any types. Is it enough that the package is found to be exported by the module?


What are the rules we must adhere to in order to implement this API?


Thanks,

Jay