Robert,
For javac and javadoc, --patch-module is also permitted for sources; it
was a late change/addition towards the end of JDK 9.
In the test case you are playing with, is com.io7m.bugs.c a package name
as well as a module name? If not, and if you think javadoc is
misinterpreting the name as a package name, could it be that something
is wrong with your --module option, which is presumably where that name
appears on the command line.
I don't think it's the case here, but I'll also mention this ... javadoc
(and javac) will want to see definitions of all symbols mentioned (e.g.
imported) in source files you want to process. This is a since-forever
property (and sometimes an annoying one). In time, it would be good to
drop this. Until then, you can provide compiled/binary versions of any
classes that you do not want to include in the documentation. If these
classes are in totally separate modules, you can put those modules on
the module path. If those classes are in modules that you are
documenting, you'll need to put those compiled classes on the
patch-module path, although with the source of the module.
-- Jon
On 11/19/17 12:29 PM, Robert Scholte wrote:
Hi Jon,
that's what I've tried to do, but when using Marks project as example
it fails with:
[parsing completed 0ms]
[loading /modules/java.base/module-info.class]
Loading source files for package com.io7m.bugs.c...
javadoc: error - No source files for package com.io7m.bugs.c
1 error
I'm kind of surprised that --patch-module should work for sources,
although it seems to find the module descriptors.
Docs say
--patch-module module=file(file*)
Overrides arguments in a module with classes and resources in JAR
files or directories.
It is not referring to source folders, which could be the reason why I
got the error.
Could it be that we're actually missing an argument for this case,
something like --patch-module-source?
thanks,
Robert
On Sun, 19 Nov 2017 19:50:08 +0100, Jonathan Gibbons
<[email protected]> wrote:
If you are wanting to generate javadoc for multiple modules, you
have two possibilities ...
From the command line ...
Yes, you must use --module-source-path, but it allows a syntax for
cases like this.
It does require that the source for each module must be "under" a
directory with the same name as the module, but it needn't be
"directly under". Like other paths, the module source path can be
a series of entries separated by the standard platform path
separator character (':' on Mac/Linux, ';' on Windows, etc). Each
entry can be of the form
//path/to/module//*//relative/path/to/source/
In that, the '*' is the literal character '*' and it stands for
the module name. The character must be present as seen by
javadoc/javac, meaning it should be escaped if necessary to pass
it through your shell or anything else that might interpret it as
a filesystem wildcard. The '*' is not a general wildcard; it is a
marker to identify the module-name within the overall entry, to
help separate the two parts before and after the '*'.
The /path/to/module/ should be a file system path to a directory
containing one or more modules, each represented by a directory
named for the module.
The /relative/path/to/source can be used to define how to locate
the source directory under the module-named directory.
The /relative/path/to/source can be omitted if empty: if the
source is directly under the module-named directory.
The '*' can be omitted if the /relative/path/to/source is omitted:
i.e. if the '*' would be at the end of the entry.
In your case, it looks like the /relative/path/to/source is
/src/main/java.
From the API:
If you are using the javax.tools.DocumentationTool API and a
JavaFileManager to invoke javadoc, there is API equivalent to the
command line support, but in addition, there is a
setLocationForModule method on StandardJavaFileManager that allows
you to specify the exact file system path(s) for the source for
each module you want to put on the module source path.
There is one other solution ... but it comes more in the
"advanced" category, but may be reasonable in the context of the
Maven plugin.
You can use
--patch-module /module-name/=/path/
to specify the source path for each module. You can give the
option multiple times, but at most once for any given module.
You must still also set the module source path, but if you use
--patch-module to specify the paths for all the modules you are
interested in, the module source path can just point to an empty
directory,
--module-source-path //path/to/empty/dir/
In this scenario, the --module-source-path option is just being
used as a "marker option" to tell javadoc to accept multiple modules,
Hope that helps.
-- Jon
On 11/18/17 11:10 AM, Mark Raynsford wrote:
Hello.
We're in the process of trying to get the maven-javadoc-plugin to work
correctly when generating documentation for modules. I have a simple
test case here that fails:
https://github.com/io7m/maven-javadoc-bug-20171118
See the README.txt for the full build log and error messages.
I think, at a basic level, we want to do this:
javadoc \
-verbose \
-sourcepath "a/src/main/java:b/src/main/java:c/src/main/java" \
--module com.io7m.bugs.a,com.io7m.bugs.b,com.io7m.bugs.c
But this of course fails with:
javadoc: error - cannot use source path for multiple modules
com.io7m.bugs.a, com.io7m.bugs.b, com.io7m.bugs.c 1 error
I note that there's --module-source-path option, so I'd expect the
following to work:
javadoc \
-verbose \
--module-source-path \
"a/src/main/java:b/src/main/java:c/src/main/java" \
--module com.io7m.bugs.a,com.io7m.bugs.b,com.io7m.bugs.c
Unfortunately, this fails with:
javadoc: error - module com.io7m.bugs.a not found.
1 error
I can't get any more information out of the javadoc tool than that, so
I'm not sure exactly what's wrong. It's been suggested to me that the
problem might be that the --module-source-path expects each entry in the
path to be a directory containing a directory named after the
respective module, but that's obviously not going to happen in a
project with sources laid out in the Maven convention (unless we start
inserting symlinks everywhere).
What's the least painful way that we can update the javadoc plugin so
that it can generate JavaDoc for a given set of modules?
