The maven-javadoc-plugin on JDK 9

[Robert Scholte]

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  
<jonathan.gibbons at oracle.com> 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  
>> <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/20171120/0168be90/attachment-0001.html>