maven javadoc:fix 无法自动修复文档

Question

我正在将 MWS Feeds API 项目从 Ant 迁移到 Maven。参见 MWS Feeds Maven port。

我在执行 mvn javadoc:fix.

时总是遇到同样的错误，这对我来说毫无意义

[ERROR] Failed to execute goal org.apache.maven.plugins:maven-javadoc-plugin:3.2.0:fix (default-cli) on project amazon-mws-feeds-maven: Execution default-cli of goal org.apache.maven.plugins:maven-javadoc-plugin:3.2.0:fix failed: A required class was missing while executing org.apache.maven.plugins:maven-javadoc-plugin:3.2.0:fix: com/amazonaws/mws/feeds/model/ReportInfo (wrong name: com/amazonaws/mws/feeds/model//ReportInfo)

我的 Maven 版本：

Java version: 11.0.2, vendor: Oracle Corporation, runtime: /Users/dmytro/.sdkman/candidates/java/11.0.2-open
Default locale: en_GB, platform encoding: UTF-8
OS name: "mac os x", version: "10.15.6", arch: "x86_64", family: "mac"

如何调试和修复它？我在 Whosebug 上搜索过，通过自然搜索和运行 mvn -X clean install 搜索过，但到目前为止没有结果。

Answer 1

@DmytroChasovskyi 这不是答案，而是您可以尝试的一组操作，以帮助解决问题。

可能您已经尝试过，但如果不是这样，请调用独立的 Maven 目标，并使用 -e 标志。

mvn -e javadoc:fix

也许它将为您提供有关正在发生的事情的更多信息。

尽量减少应修复的元素数量。正如您在 docs 中看到的那样，您有一些标志允许您选择是否应修复类、字段或方法注释。玩玩吧，可能会有一些帮助。

您还可以更改 jdk 合规级别：您正在为 Java 1.6 进行编译。只是为了提前解决问题，如果可能的话，使用另一个java目标版本。

您可以尝试的最后一件事是使用另一个 JVM 来执行构建，然后发现问题仍然存在。

最后，Maven的修复目标Javavoc Plugin高度依赖QDOX；这可能是一些工作，但也许您可以直接使用该库实施一些测试并尝试处理您的代码以查看问题是否仍然存在。

Answer 2

假设

错误消息暗示类型解析失败（缺少class），这似乎是因为插件试图解析稍微无效路径（注意中的双斜杠“错误名称：com/amazonaws/mws/feeds/model//ReportInfo”）。

确定问题

我从 mvn -X javadoc:fix 开始，以便启用调试。输出非常有帮助：

[DEBUG] Analyzing com.amazonaws.mws.feeds.model.GetFeedSubmissionListByNextTokenResult
[INFO] Saving changes to com.amazonaws.mws.feeds.model.GetFeedSubmissionListByNextTokenResult
[DEBUG] Analyzing com.amazonaws.mws.feeds.model.UpdateReportAcknowledgementsResult
[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------

最后 class 成功处理的是 GetFeedSubmissionListByNextTokenResult（处理顺序并不总是相同，但无关紧要）但 UpdateReportAcknowledgementsResult 失败。现在我们可以专注于这个 class.

进一步调查堆栈跟踪发现异常发生在插件修复（替换）link 标签（熟悉的 {@link ClassName} javadoc 标签）时：

    at com.thoughtworks.qdox.type.TypeResolver.resolveTypeInternal (TypeResolver.java:187)
    at com.thoughtworks.qdox.type.TypeResolver.resolveType (TypeResolver.java:119)
    at org.apache.maven.plugins.javadoc.AbstractFixJavadocMojo.replaceLinkTags (AbstractFixJavadocMojo.java:1858)
    at org.apache.maven.plugins.javadoc.AbstractFixJavadocMojo.updateJavadocComment (AbstractFixJavadocMojo.java:1808)
    at org.apache.maven.plugins.javadoc.AbstractFixJavadocMojo.updateJavadocComment (AbstractFixJavadocMojo.java:1756)
    at org.apache.maven.plugins.javadoc.AbstractFixJavadocMojo.updateEntityComment (AbstractFixJavadocMojo.java:1632)
    at org.apache.maven.plugins.javadoc.AbstractFixJavadocMojo.fixMethodComment (AbstractFixJavadocMojo.java:1486)
    at org.apache.maven.plugins.javadoc.AbstractFixJavadocMojo.processFix (AbstractFixJavadocMojo.java:1100)

现在我们知道要在 class 中搜索什么了。

根本原因

真正的问题很明显，例如 UpdateReportAcknowledgementsResult:147

     // @param values a {@link .ReportInfo} object.

QDOX 的 TypeResolver 未正确处理 class 名称之前的那个点。一旦我删除了所有 {@link .X} 个事件，插件就成功执行了。

我的猜测是这些点是在大规模 find-and-replace 操作期间错误地放置在那里的。 我的一个朋友曾经做过类似的事情...

maven javadoc:fix 无法自动修复文档

maven javadoc:fix fails to autofix docs

java

maven

maven-javadoc-plugin

假设

确定问题

根本原因