Fwd: Re: running javadoc against multiple modules

[Jonathan Gibbons]

Sorry, I missed that detail when looking at your example yesterday.

The error message says it all.

When you're working with multiple modules on the module source path, 
each module must be in a directory that is named after the module it 
contains. Think of it as the module-level equivalent of the requirement 
that classes in a package hierarchy should be organized in a directory 
hierarchy that mirrors the package hierarchy.

If your modules are named org.test.firstmodule and 
org.test.secondmodule, your ./java directory should contain direct 
subdirectories with those exact names.  Within each directory, you can 
place the package hierarchy for the content of that module. In simple 
cases, you can place the package hierarchy directly in the module 
directory, although with a more complex value for the 
--module-source-path option, you can set up a system with intervening 
directories between the module directory and the root of the package 
hierarchy.

The module paths are described in JEP 261. 
http://openjdk.java.net/jeps/261  Although that JEP does not call out 
javadoc, the description for javac essentially applies to javadoc as well.

-- Jon


On 5/29/18 4:02 PM, Rick Hillegas wrote:
>
> Thanks, Jon. That moved the problem forward. Now I am getting an error 
> because a module's name does not match the root directory of its 
> source code. The following command...
>
>    javadoc --module-source-path ./java \
>       -d build/javadoc \
>       --module firstmodule,secondmodule
>
>
> ...raises the following errors:
>
>    ./java/secondmodule/module-info.java:1: error: module name org.test.secondmodule
>     does not match expected name secondmodule
>    module org.test.secondmodule
>    ^
>    ./java/secondmodule/module-info.java:5: error: module not found:
>      org.test.firstmodule
>      requires org.test.firstmodule;
>                       ^
>    error: cannot access module-info
>      cannot resolve modules
>    3 errors
>
>
> I get a different error when I change the names of the modules which I 
> hand to the --module switch. The following command...
>
>    javadoc --module-source-path ./java \
>      -d build/javadoc \
>      --module org.test.firstmodule,org.test.secondmodule
>
>
> ...raises the following error...
>
>    javadoc: error - module org.test.firstmodule not found.
>
>
> I have attached a tarball of my project.
>
> Thanks for any advice you can give me,
> -Rick
>
>
>
> -------- Forwarded Message --------
> Subject: 	Re: running javadoc against multiple modules
> Date: 	Tue, 29 May 2018 11:33:10 -0700
> From: 	Jonathan Gibbons <jonathan.gibbons at oracle.com>
> To: 	javadoc-dev at openjdk.java.net
>
>
>
> Rick,
>
> Set --module-sourcepath to the directory containing the modules.
>
> Something like this should work for you:
>
>      javadoc  --module-source-path ./java -d build/javadoc --module
> firstmodule,secondmodule
>
> -- Jon
>
> On 05/20/2018 04:45 PM, Rick Hillegas wrote:
> > 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
> >
>
>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20180530/ef8bfffc/attachment.html>