How do I create a Javadoc link to a class in a sibling module?

Question

Given that:

• markdown javadoc comments can link to references
• references are defined like this, specifically:

  The most general form of a reference is:

  module/package.class#member

• This project structure:

.
├── build.gradle
├── com.example.moduleone
│  ├── build.gradle
│  └── src
│  └── main
│  └── java
│  ├── com
│  │  └── example
│  │  └── botany
│  │  ├── fruit
│  │  │  └── Tomato.java
│  │  └── package-info.java
│  └── module-info.java
├── com.example.moduletwo
│  ├── build.gradle
│  └── src
│  └── main
│  └── java
│  ├── com
│  │  └── example
│  │  └── food
│  │  ├── package-info.java
│  │  └── vegetable
│  │  └── Potato.java
│  └── module-info.java
├── gradle
│  └── wrapper
│  ├── gradle-wrapper.jar
│  └── gradle-wrapper.properties
├── gradlew
├── gradlew.bat
├── lib
│  └── markista.docagrams.jar
└── settings.gradle

I would assume that with the correct Javadoc command options, the following Javadoc comment will be rendered as a link to the Tomato class in com.example.moduleone:

/// [com.example.moduleone/com.example.botany.fruit.Tomato] is a reference to a class 
 

Instead, when I run javadoc, I get an error:

javadoc -d build/doc/com.example.moduletwo \
 --module-path com.example.moduleone/build/classes/java/main:com.example.moduletwo/build/classes/java/main \
 --source-path com.example.moduleone/src/main/java:com.example.moduletwo/src/main/java \
 -subpackages com.example.food.vegetable:com.example.botany.fruit \
 -link ../com.example.moduleone --add-modules com.example.moduleone \
 com.example.moduletwo/src/main/java/module-info.java \
 com.example.moduletwo/src/main/java/com/example/food/vegetable/Potato.java \
 com.example.moduletwo/src/main/java/com/example/food/package-info.java
Loading source file com.example.moduletwo/src/main/java/module-info.java...
Loading source file com.example.moduletwo/src/main/java/com/example/food/vegetable/Potato.java...
Loading source file com.example.moduletwo/src/main/java/com/example/food/package-info.java...
Loading source files for package com.example.food.vegetable...
Loading source files for package com.example.botany.fruit...
Constructing Javadoc information...
Creating destination directory: "build/doc/com.example.moduletwo/"
error: Error reading file: build/doc/com.example.moduletwo/../com.example.moduleone/element-list
Building index for all the packages and classes...
Standard Doclet version 24.0.1
Building tree for all the packages and classes...
Generating build/doc/com.example.moduletwo/com.example.moduletwo/com/example/food/vegetable/Potato.html...
Generating build/doc/com.example.moduletwo/com.example.moduletwo/com/example/botany/fruit/Tomato.html...
Generating build/doc/com.example.moduletwo/com.example.moduletwo/com/example/botany/fruit/package-summary.html...
Generating build/doc/com.example.moduletwo/com.example.moduletwo/com/example/botany/fruit/package-tree.html...
Generating build/doc/com.example.moduletwo/com.example.moduletwo/com/example/food/vegetable/package-summary.html...
Generating build/doc/com.example.moduletwo/com.example.moduletwo/com/example/food/vegetable/package-tree.html...
Generating build/doc/com.example.moduletwo/com.example.moduletwo/module-summary.html...
Generating build/doc/com.example.moduletwo/overview-tree.html...
Generating build/doc/com.example.moduletwo/allclasses-index.html...
Building index for all classes...
Generating build/doc/com.example.moduletwo/allpackages-index.html...
Generating build/doc/com.example.moduletwo/index-all.html...
Generating build/doc/com.example.moduletwo/search.html...
Generating build/doc/com.example.moduletwo/index.html...
Generating build/doc/com.example.moduletwo/help-doc.html...
1 error

The full path to the Tomato class and its source is:

com.example.moduleone/build/classes/java/main/com/example/botany/fruit/Tomato.class
com.example.moduleone/src/main/java/com/example/botany/fruit/Tomato.java

module-info.java from com.example.moduleone:

/// Example module
module com.example.moduleone {
 exports com.example.botany.fruit;
}

module-info.java from com.example.moduletwo:

/// Example module
module com.example.moduletwo {
 exports com.example.food.vegetable;
}

Git repo with reproducible problem:

https://github.com/sandydunlop/javadoc-reference-not-found

• dan1st: Can you try adding requires com.example.moduleone; or at least requires static com.example.moduleone; to the module-info.java of com.example.moduletwo?

Answer 1

Maybe you need to run Javadoc on moduleone before moduletwo can pick it up?

• Sandy Dunlop: Yes, I think something was wrong with my gradle build file. I've re-rwitten it and the problem seems to have gone away now. I suspect as you said it wasn't generating moduleone's elements-list before it was trying to build moduletwo's docs.
• Slaw: @SandyDunlop Testing things out, it does look like that's the problem. But if subproject B depends on subproject A, then running ./gradlew javadoc should cause subproject A to build its Javadoc first, letting the Javadoc of subproject B succeed. However, I'm seeing that the links are file URIs, so I don't know that the links will work if you publish your Javadoc (even if just via javadoc.io). You may want to consider creating "aggregate" Javadocs. Since you're apparently using JPMS, that should involve specifying the --module-source-path and --module arguments.