I have generated javadoc with javadoc maven plugin 3.0.1 and Java 9. However, when I use the new Search capability and pick a class, it redirects to "File not found"...
There is undefined
in the url (e.g. "../target/site/apidocs/undefined/com/mycompany/MyClass.html"), which if removed, loads the page correctly.
Could you please help me with the right configuration to generate java doc (get rid of this undefined
), so the search capability load the html page fine?
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>${version.maven-javadoc-plugin}</version>
<executions>
<execution>
<id>javadoc</id>
<goals>
<goal>javadoc</goal>
</goals>
<phase>prepare-package</phase>
<configuration>
<doclint>none</doclint>
<dependencySourceIncludes>
<dependencySourceInclude>com.some:some</dependencySourceInclude>
</dependencySourceIncludes>
<doctitle>Title - ${project.version}</doctitle>
<includeDependencySources>true</includeDependencySources>
<windowtitle>Title</windowtitle>
</configuration>
</execution>
</executions>
Got this working with the help of the following option in the java doc maven plugin configuration
<additionalJOption>--no-module-directories</additionalJOption>
This is a bit of a hack, but as @Martin Goik has mentioned in his answer, specifying --no-module-directories
breaks any external links to standard classes due to missing module names. As the OP has mentioned in a comment, getURLPrefix(ui)
of search.js
is what generates the module names. So after some digging around, I found that the problem can be fixed by appending this to the end of search.js
:
getURLPrefix = function(ui) {
return "";
};
which essentially overwrites the definition of getURLPrefix
to return an empty string no matter what. As it only needs to be appended to the end of a file, it should be easy enough to automate with any build tool by code or a command.
For example, if you're using Gradle, the following can be added to build.gradle
:
// Needed to fix Javadoc search
// See comments below
final JAVADOC_FIX_SEARCH_STR = '\n\n' +
'getURLPrefix = function(ui) {\n' +
' return \'\';\n' +
'};\n'
tasks.withType(Javadoc) {
// Link to external docs
options.with {
// Example: Java 11 API documentation
links 'https://docs.oracle.com/en/java/javase/11/docs/api/'
}
doLast {
// Append the fix to the file
def searchScript = new File(destinationDir.getAbsolutePath() + '/search.js')
searchScript.append JAVADOC_FIX_SEARCH_STR
}
}
Each .html
file generated by Javadoc contains the following variable definition:
var useModuleDirectories = true;
which affects the behavior of the getURLPrefix()
function in search.js
:
function getURLPrefix(ui) {
var urlPrefix="";
if (useModuleDirectories) {
...
}
return urlPrefix;
}
Therefore, we can work around this issue by overriding the value of useModuleDirectories
with false
, which is possible by specifying the following script tag in the -bottom
option:
<script>
if (typeof useModuleDirectories !== 'undefined') {
useModuleDirectories = false;
}
</script>
Note that you must specify the --allow-script-in-comments
option as well so that Javadoc does not complain about using the <script/>
tags in comments.
Using the Javadoc maven plugin
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>${javadoc.pluginVersion}</version>
<executions>
<execution>
<id>javadoc</id>
<goals>
<goal>javadoc-no-fork</goal>
<goal>jar</goal>
</goals>
<phase>process-resources</phase>
<configuration>
<bottom>
<![CDATA[
<script>
if (typeof useModuleDirectories !== 'undefined') {
useModuleDirectories = false;
}
</script>
]]>
</bottom>
<additionalJOption>--allow-script-in-comments</additionalJOption>
This bug should be fixed in JDK 12: https://bugs.openjdk.java.net/browse/JDK-8215291
Credit goes to Chris Povirk for locating the relevant bug report.
This indeed resolves the «Search» linking to ../undefined/... problem. There is however a nasty side effect: Links to standard classes or interfaces directing towards e.g. https://docs.oracle.com/en/java/javase/12/docs/api/
... will be broken due to missing module names.
Consider e.g. links to java.lang.String
now incorrectly pointing to https://docs.oracle.com/en/java/javase/12/docs/api/java/lang/String.html
rather than towards https://docs.oracle.com/en/java/javase/12/docs/api/
java.base/java/lang/String.html
.
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