running javadoc against multiple modules

[Rick Hillegas]

I hope that someone can point me at the right documentation for how to 
create javadoc on a multi-module project. My naive googling does not 
find any pertinent examples for how to do this from the command line via 
the javadoc tool. I have looked through the Java 9 tools documents 
titled "Javadoc Guide" and "Tools Reference" but I have not been able to 
puzzle out which combination of options will produce a single, unified 
set of javadoc for multiple modules. This is my first attempt to 
document a multi-module project, so, no doubt, I am missing something 
simple but crucial.

I am using "Java(TM) SE Runtime Environment (build 9+181)". My source 
tree looks like this:

./java
./java/firstmodule
./java/firstmodule/firstpackage
./java/firstmodule/firstpackage/FirstClass.java
./java/firstmodule/module-info.java
./java/secondmodule
./java/secondmodule/module-info.java
./java/secondmodule/secondpackage
./java/secondmodule/secondpackage/SecondClass.java


The module descriptors look like the following...

module org.test.firstmodule

{
     requires java.base;
     exports firstpackage;
}


...and...

module org.test.secondmodule

{
     requires java.base;
     requires org.test.firstmodule;
     exports secondpackage;
}


I believe that I have written valid modules, because the following 
command does what I expect it to do:

   java -p build/jars/firstmodule.jar:build/jars/secondmodule.jar \
        -m org.test.secondmodule/secondpackage.SecondClass


That is, the java command likes my modules well enough. But javadoc 
baffles me.

The following command...

   javadoc -sourcepath ./java/firstmodule:./java/secondmodule \
          -d build/javadoc \
          firstpackage secondpackage


...runs without any errors or warnings. However, it produces odd results:

1) The top level index.html page lists only one module: 
org.test.firstmodule. I expected to see both modules on the landing page.

2) In addition, SecondClass.html reports that SecondClass lives in the 
org.test.firstmodule module. I expected that the class would report its 
home as org.test.secondmodule.

The following command...

   javadoc --module-source-path ./java/firstmodule:./java/secondmodule \
           -d build/javadoc \
           firstpackage secondpackage


...raises the following error...

   javadoc: error - No source files for package firstpackage


And this command...

   javadoc --module-source-path ./java/firstmodule:./java/secondmodule \
           --module org.test.firstmodule,org.test.secondmodule \
           -d build/javadoc \
           firstpackage secondpackage


...objects that...

   javadoc: error - module org.test.firstmodule not found.


Clearly, I've wandered off into the tall weeds. I would appreciate your 
advice and, if possible, a pointer to a primer on this topic.

Thanks,
-Rick