The maven-javadoc-plugin on JDK 9

[Robert Scholte]

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=pathto 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/9a82d6fb/attachment.html>