Menu
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.
779
Javadoc provides the @link inline tag for referencing the members in the Java classes. We can think of the @link tag as similar to the anchor tag in HTML, which is used to link one page to another via hyperlinks. Similar to the anchor tag, the path_to_member is the destination, and the label is the display text.
Nope, you shouldn't write javadoc for private methods. End users don't have access to private fields or methods so there really isn't a point in providing javadoc for them. Private fields and methods are only meant for the developer. If you really need to though, feel free to write comments for non-obvious logic.
In short, we use the @see tag when we want a link or a text entry that points to a reference. This tag adds a “See Also” heading to the reference. A document comment can hold any number of @see tags, all of which can be grouped under the same heading.
Creating a Link to Javadoc of Another Class This tag can be used anywhere that a comment can be written, while @see creates its own section. To summarize, @link is preferred when we use a class or method name in the description.
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.
183
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With
