maven javadoc：修复无法自动修复文档

Question

我正在将MWS提要API项目从Ant迁移到Maven。参见MWS馈送Maven端口。

在执行mvnjavadoc:fix时，我总是遇到同样的错误，这对我来说毫无意义。

[错误]未能执行目标org.apache.maven.plugins：maven-javadoc-plugin：3.2.0：修复（default-cli）对项目amazon-mws-feeds-maven：执行default-cli的目标org.apache.maven.plugins：maven-javadoc-plugin：3.2.0：修复失败：一个必需的类是在执行org.apache.maven.plugins：maven-javadoc-plugin：3.2.0：修复：com/amazonaws/mws/feeds/Model/ReportInfo（错误名称：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"

我如何调试和修复它？我在StackOverflow上进行了搜索，通过自然搜索进行了搜索，并运行了mvn-X清洁安装，但到目前为止没有结果。

Answer 1

@DmytroChasovskyi这不是一个答案，而是一系列可以尝试的事情，以帮助解决问题。

可能您已经尝试过了，但如果不是这样，请使用-e标志调用maven目标，隔离。

mvn -e javadoc:fix

也许它会给你更多的关于正在发生的事情的信息。

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

您还可以更改jdk遵从性级别：您正在为Java1.6编译。为了进一步解决问题，如果可能的话，使用另一个java目标版本。

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

最后，Maven Javavc插件的修复目标高度依赖于QDOX；这可能是一些工作，但也许你可以直接用这个库实现一些测试，并尝试处理你的代码，看看问题是否仍然存在。

Answer 2

错误消息意味着类型解析失败（类丢失），这似乎是因为插件试图解析一个稍微无效的路径（请注意“错误的名称： 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] ------------------------------------------------------------------------

成功处理的最后一个类是GetFeedSubmissionListByNextTokenResult（处理顺序并不总是相同，但这并不相关），但UpdateReportAcknowlementsResult失败。现在我们可以关注这门课了。

对堆栈跟踪的进一步调查显示，插件修复（替换）链接标记（熟悉的{@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)

现在我们知道该在该类中搜索什么了。

真正的问题是显而易见的，例如在更新报告确认结果： 147

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

类名前的点在QDOX的TypeResolver中没有正确处理。一旦我删除了所有出现的{@link.X}，插件就成功执行了。

我猜这些点是在一次大规模的寻找和替换行动中被错误地放在那里的。我的一个朋友曾经做过类似的事情...