The maven-javadoc-plugin on JDK 9

Sun Nov 19 21:24:45 UTC 2017

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 
> <jonathan.gibbons at oracle.com> 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?
>>
>
>
>
>

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