That seems like a bug that needs to be fixed.
As well as applications, there are also service-provider modules, which
deserve to be documented, but which may not export API.
-- Jon
On 11/20/17 12:01 PM, Robert Scholte wrote:
Hi Jon,
I've found the problem. The issue is that the module descriptor of c
doesn't export any packages.
Considering c is an application, it makes sense because that code is
not shared for third parties.
But what if you are using javadoc as documentation of your code?
Can this be solved *without* adding exports to the module descriptor
just for javadoc purpose?
"--show-packages all" still comes with the same error message.
thanks,
Robert
On Sun, 19 Nov 2017 22:24:45 +0100, Jonathan Gibbons
<[email protected]> wrote:
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?
