Fwd: Re: running javadoc against multiple modules
Rick Hillegas
rick.hillegas at gmail.com
Wed May 30 23:08:09 UTC 2018
Thanks for that explanation, Jon.
I'm asking these questions because I'm near the end of modularizing a
very old body of software, Apache Derby. I have successfully created
module descriptors for all of the Derby components and I have not had to
rename any directories. The naming limitation you describe does not
constrain javac. Javac does not impose any restrictions on the names of
the root directories of components.
I do not see this limitation in JEP 261. Stephen Colbourne seems to
recommend the practice which you are advocating
(http://blog.joda.org/2017/04/java-se-9-jpms-module-naming.html) but he
merely states a strong recommendation. My sense is that it is a best
practice for greenfield projects. It is clearly a big hurdle for legacy
projects to surmount.
Thanks for this clarification,
-Rick
On 5/30/18 7:34 AM, Jonathan Gibbons wrote:
>
> 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/97abbdfe/attachment.html>
More information about the javadoc-dev
mailing list