The maven-javadoc-plugin on JDK 9
Jonathan Gibbons
jonathan.gibbons at oracle.com
Mon Nov 20 20:30:40 UTC 2017
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
> <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/=/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/20171120/0b67b1d5/attachment.html>
More information about the javadoc-dev
mailing list