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

Question

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

有undefined在URL(如"../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在他的回答中提到的那样，指定--no-module-directories会由于缺少模块名称而破坏到标准类的任何外部链接。正如OP在评论中提到的，getURLPrefix(ui)ofsearch.js是生成模块名称的东西。因此，经过一番挖掘后，我发现可以通过将其附加到末尾来解决问题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

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

var useModuleDirectories = true;

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

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

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

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

请注意，您还必须指定该--allow-script-in-comments选项，以便 Javadoc 不会抱怨<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找到了相关的错误报告。