The -link option on the javadoc command in java 10 isn't working consistently for me with modules.
Specifically, it doesn't work where a dependent module name is the same as the name of the package it exports
I run the following command
/opt/jdk-10.0.1/bin/javadoc -html5
-subpackages uk.co.sr.vcher.service \
--source-path src/service \
--module-path lib:app -d javadoc/service \
-link ../auth -link ../db -link ../models \
-link ../core -link ../render \
-link https://docs.oracle.com/javase/10/docs/api \
-linksource src/service/uk/co/sr/vcher/service/Service.java \
src/service/uk/co/sr/vcher/service/ServiceImpl.java \
src/service/module-info.java
So that is generating javadoc for two classes in package uk.co.sr.vcher.service, which are under src/service, and linking the docs to 5 other modules in my application, plus the jdk docs
The module jars I built are in app/ , external dependencies are in lib/
Javadoc succeeds and generates the HTML. But the links to classes in some (not all) of other modules of my application are broken, missing the path directories of the package.
What I'm showing below is a piece of the HTML output for one constructor of uk.co.sr.vcher.service.ServiceImpl. It takes four parameters: a File, a ConnectionSource, a Coder, and an ApplicationConfig
I've taken out the link attached to ServiceImpl, and added some whitespace, for readability. It's the links attached to the four parameter types that I'm concerned with.
the File is java.io.File and correctly links to docs.oracle.com
the ConnectionSource is uk.co.sr.vcher.db.ConnectionSource and while the tooltip shows the package correctly, and the link goes to the javadoc for the right module uk.co.sr.db, the link is wrong, as it doesn't include the path of the package
the Coder is uk.co.sr.vcher.Coder from module uk.co.sr.vcher.core. In this case the link is correct, to core/uk/co/sr/vcher/Coder.html
the ApplicationConfig, like the Coder, is from package uk.co.sr.vcher in module uk.co.sr.vcher.core, and the link is correct.
Throughout my project, links to two modules are correct, but to all other modules are broken by missing the package path.
I've created the javadoc for each of my modules in the same way. They contain element-list files at their base, not package-list files. The uk.co.sr.vcher.service module depends on the uk.co.sr.vcher.db and uk.co.sr.vcher.core modules.
As far as I can see, the difference between the modules which I can link to successfully and the ones that I can't are that the "good" ones aren't in subpackages of anything else. i.e. module uk.co.sr.vcher.db contains package uk.co.sr.vcher.db which is a subpackage of package uk.co.sr.vcher, which is contained in module uk.co.sr.vcher.core. But that isn't supposed to break anything.
<span class="memberNameLink">
ServiceImpl</span>(
<a href="https://docs.oracle.com/javase/10/docs/api/java/io/File.html?is-
external=true"
title="class or interface in java.io"
class="externalLink">File</a> workDirectory,
<a href="../../../../../../db/ConnectionSource.html?is-
external=true"
title="class or interface in uk.co.sr.vcher.db"
class="externalLink">ConnectionSource</a> db,
<a href="../../../../../../core/uk/co/sr/vcher/Coder.html?is-
external=true"
title="class or interface in uk.co.sr.vcher"
class="externalLink">Coder</a> coder,
<a href="../../../../../../core/uk/co/sr/vcher/ApplicationConfig.html?is-
external=true"
title="class or interface in uk.co.sr.vcher"
class="externalLink">ApplicationConfig</a> config)
Update: I've put a minimal example project -- three java classes, three modules -- that shows the same problem at https://github.com/andrewmcguinness/javadoc_issue
Update 2: I pinned down the cause to the name of the package uk.co.sr.vcher.db being the same as the name of the module uk.co.sr.vcher.db. Changing the module name to uk.co.sr.vcher.pdb fixes it. I still want to know if this is a jdk bug or if I'm doing something wrong.
I'm going to go ahead and call this a javadoc bug. I don't really understand the javadoc code, but it looks quite likely that it stores packages and modules in the same dictionary internally, so if a module has the same name as a package, it overwrites the package information. Then when it has to look up the path of the package, it fails and defaults to empty string.
I've reported the bug to Oracle. Will update if that results in anything useful.
The workaround is to rename your module (uk.co.sr.vcher.db in my example) to something that isn't a name of one of the exported packages.