The maven-javadoc-plugin on JDK 9

classic Classic list List threaded Threaded
9 messages Options
Reply | Threaded
Open this post in threaded view
|

The maven-javadoc-plugin on JDK 9

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

--
Mark Raynsford | http://www.io7m.com

attachment0 (849 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

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


Reply | Threaded
Open this post in threaded view
|

Re: The maven-javadoc-plugin on JDK 9

Mark Raynsford
'Ello.

Thanks for the detailed response!

On 2017-11-19T10:50:08 -0800
Jonathan Gibbons <[hidden email]> wrote:

>
> 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,
This one is almost certainly the one we'll go with. It assumes less
about the directory hierarchy than the other options, so it seems the
easiest to fit into the existing system.

--
Mark Raynsford | http://www.io7m.com


attachment0 (849 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: The maven-javadoc-plugin on JDK 9

Robert Scholte
In reply to this post by Jonathan Gibbons
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 <[hidden email]> 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?





Reply | Threaded
Open this post in threaded view
|

Re: The maven-javadoc-plugin on JDK 9

Jonathan Gibbons

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 [hidden email] 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?






Reply | Threaded
Open this post in threaded view
|

Re: 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 <[hidden email]> 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 [hidden email] 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?









Reply | Threaded
Open this post in threaded view
|

Re: The maven-javadoc-plugin on JDK 9

Jonathan Gibbons

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 [hidden email] 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 [hidden email] 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?










Reply | Threaded
Open this post in threaded view
|

Re: The maven-javadoc-plugin on JDK 9

Jonathan Gibbons
In reply to this post by Robert Scholte
Does this mean we have a secondary bug, that the error message you got
said "package" when it meant "module"?

-- Jon


On 11/20/17 12:01 PM, Robert Scholte wrote:
>
> javadoc: error - No source files for package com.io7m.bugs.c

Reply | Threaded
Open this post in threaded view
|

Re: The maven-javadoc-plugin on JDK 9

Robert Scholte
I guess so :)

thanks,
Robert

ps. can you add the label apache-maven-found to the issues so we can  
easily follow progress?

On Mon, 20 Nov 2017 21:33:33 +0100, Jonathan Gibbons  
<[hidden email]> wrote:

> Does this mean we have a secondary bug, that the error message you got  
> said "package" when it meant "module"?
>
> -- Jon
>
>
> On 11/20/17 12:01 PM, Robert Scholte wrote:
>>
>> javadoc: error - No source files for package com.io7m.bugs.c