Maven javadoc 搜索重定向到“/undefined/..” url

Question

我已经使用 javadoc maven 插件 3.0.1 和 Java 9 生成了 javadoc。但是，当我使用新的搜索功能并选择一个类时，它会重定向到“找不到文件”...

网址中有undefined（例如“../target/site/apidocs/undefined/com/mycompany/MyClass.html”），如果将其删除，则可以正确加载页面。

能否请您帮助我正确配置以生成 java doc（摆脱这个 undefined），以便搜索功能可以正常加载 html 页面？

<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>

Answer 1

在 java doc maven 插件配置中的以下选项的帮助下完成了这项工作

<additionalJOption>--no-module-directories</additionalJOption>

Answer 2

这有点小技巧，但正如@Martin Goik 在his answer 中提到的那样，由于缺少模块名称，指定--no-module-directories 会破坏任何指向标准类的外部链接。正如 OP 在评论中提到的那样，search.js 的 getURLPrefix(ui) 是生成模块名称的原因。所以经过一番挖掘，我发现问题可以通过将其附加到search.js的末尾来解决：

getURLPrefix = function(ui) {
    return "";
};

它本质上覆盖了getURLPrefix 的定义，无论如何都返回一个空字符串。由于它只需要附加到文件的末尾，因此应该很容易通过代码或命令使用任何构建工具进行自动化。

例如，如果您使用的是 Gradle，则可以将以下内容添加到 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
    }
}

Answer 3

Javadoc 生成的每个.html 文件都包含以下变量定义：

var useModuleDirectories = true;

这会影响search.js 中getURLPrefix() 函数的行为：

function getURLPrefix(ui) {
    var urlPrefix="";
    if (useModuleDirectories) {
        ...
    }
    return urlPrefix;
}

---

---

因此，我们可以通过用false 覆盖useModuleDirectories 的值来解决此问题，这可以通过在-bottom 选项中指定以下脚本标记来实现：

<script>
if (typeof useModuleDirectories !== 'undefined') {
  useModuleDirectories = false;
}
</script>

请注意，您还必须指定--allow-script-in-comments 选项，以便Javadoc 不会抱怨在cmets 中使用<script/> 标记。

---

使用 Javadoc maven 插件

<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>

Answer 4

这个错误应该在 JDK 12 中修复：https://bugs.openjdk.java.net/browse/JDK-8215291

感谢 Chris Povirk 查找相关错误报告。

Answer 5

这确实解决了链接到 ../undefined/... 的 «Search» 问题。然而，有一个讨厌的副作用：指向标准类或接口的链接，例如https://docs.oracle.com/en/java/javase/12/docs/api/... 将因缺少模块名称而损坏。

考虑例如指向java.lang.String 的链接现在错误地指向https://docs.oracle.com/en/java/javase/12/docs/api/java/lang/String.html，而不是指向https://docs.oracle.com/en/java/javase/12/docs/api/java.base/java/lang/String.html。

Answer 6

添加 <additionalJOption>-no-module-directories</additionalJOption>

为我工作。有一个- 而不是--