Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

Linking between modules in javadoc

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>&nbsp;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.

like image 779
Andrew McGuinness Avatar asked Jun 23 '18 11:06

Andrew McGuinness


People also ask

How do you reference another method in Javadoc?

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.

Do we need Javadoc for private methods?

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.

How do you add a link to a Javadoc?

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.

What is @link in Java comments?

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.


1 Answers

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.

like image 183
Andrew McGuinness Avatar answered Sep 29 '22 16:09

Andrew McGuinness