Rick,
Thank you for explaining the context of your questions.
With respect, you are mistaken with respect to javac's behavior, if only
because it's the same code shared by javac and javadoc,
--module-source-path requires there to be a level in the directory
hierarchy that is named for the module. The name is required in order
to find the source for a module, when resolve a directive like "requires
moduleName;". Just as javac requires that classes can be looked up in a
directory hierarchy that corresponds to the package hierarchy, so too
does javac and javadoc impose a requirement that the source for a module
be in a suitably-named directory when using the module source path.
It may be that you have not encountered the equivalent situation in
javac if you have managed to compile your code one module at a time,
placing the output from previous compilations on the module path. In
that situation, would would not need to use the --module-source-path
option, which is necessary when you want to read/analyze/compile the
source code for several modules at once.
Although I grant that the text in JEP 261 could be clearer, this is the
relevant text:
In large systems the source code for a particular module may be spread
across several different directories.In the JDK itself
<http://openjdk.java.net/jeps/201>,/e.g./, the source files for a
module may be found in any one of the
directories|src/<module>/share/classes|,|src/<module>/<os>/classes|,
or|build/gensrc/<module>|, where|<os>|is the name of the target
operating system. To express this in a module source path while
preserving module identities we allow each element of such a path to
use braces (|{|and|}|) to enclose commas-separated lists of
alternatives and a single asterisk (|*|) to stand for the module name.
The module source path for the JDK can then be written as
|{src/*/{share,<os>}/classes,build/gensrc/*}|
The reference to '*' is the presence of the module name.
I understand the difficulty this restriction may cause some existing
older software systems. At some level, I'm impressed you have gotten as
far as you have without running into this restriction before!
All that having been said, there may be a way forward for you. The
following may seen a bit cumbersome, but it may allow you to run javadoc
(or javac) without renaming your source directories. You can do this
with a combination of --module-source-path and --patch-module, as follows:
1. Point --module-source-path at an empty directory. The presence of
the option is required so that the tool is put into "multi-module mode".
2. For each of the modules you want to process, use an option like this:
--patch-module <module-name>=<path-for-module-source>
The <module-name> is as it would appear in the module declaration;
the <path-for-module-source> is a "source path", meaning one or more
directories separated by the system path separator character (either ':'
on Unix-like systems, or ';' on Windows.) As a source path, the
directories on the path must all be directories at the root of a package
hierarchy.
So, for example, for one of your modules, the option would be
--patch-module org.test.firstmodule=./java/firstmodule
And you would repeat that as needed for all the other modules you
want to pass to javadoc
-- Jon
On 5/30/18 4:08 PM, Rick Hillegas wrote:
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 <[email protected]>
To: [email protected]
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
>
