The maven-javadoc-plugin on JDK 9

[Jonathan Gibbons]

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?
>

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