Maven javadoc:fix 无法自动修复文档问题。

huangapple go评论39阅读模式
英文:

maven javadoc:fix fails to autofix docs

问题

我正在将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版本:11.0.2,供应商:Oracle Corporation,运行时:/Users/dmytro/.sdkman/candidates/java/11.0.2-open
  • 默认区域设置:en_GB,平台编码:UTF-8
  • 操作系统名称:“mac os x”,版本:“10.15.6”,架构:“x86_64”,系列:“mac”

我该如何调试和解决这个问题?我在StackOverflow上搜索过,通过自然搜索进行了搜索,并运行了mvn -X clean install,但迄今为止没有结果。

英文:

I am migrating the MWS Feeds API project from Ant to Maven. See MWS Feeds Maven port.

I get all the time the same error which makes no sense for me when executing 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)

My Maven version:

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"

How can I debug and fix it? I searched on StackOverflow, searched via natural search, and run mvn -X clean install but so far no results.

答案1

得分: 1

@DmytroChasovskyi 这不是一个答案,而是一组可以尝试的方法,以帮助解决问题。

可能你已经尝试过了,但如果还没有尝试过,请单独使用以下命令并加上-e标志来调用Maven目标。

mvn -e javadoc:fix

也许它会提供更多关于问题的信息。

尝试减少需要修复的元素数量。正如您在文档中所看到的,您可以使用标志选择是否修复类、字段或方法的注释。尝试使用这些标志,可能会有所帮助。

您还可以更改JDK的兼容级别:您正在为Java 1.6进行编译。为了更进一步解决问题,如果可能的话,尝试使用另一个Java目标版本。

最后,Maven Javadoc插件的fix目标高度依赖于QDOX;也许需要一些工作,但您可以尝试直接使用该库实施一些测试,并尝试处理您的代码,以查看问题是否仍然存在。

英文:

@DmytroChasovskyi This is not an answer, but a set of things you can try in order to help to resolve the problem.

Probably you have already try it, but if it is not the case, invoke the maven goal, isolated, and with the -e flag.

mvn -e javadoc:fix

Maybe it will give you further information about what is going on.

Try to reduce the number of elements that should be fixed. As you can see in the docs, you have flags that allows you to choose whether classes, fields or methods comments should be fixed. Play with it, it could be of some help.

You can also change the jdk compliance level: you are compiling for Java 1.6. Just for advance in the resolution of the problem, if possible, use another java target version.

One last thing you can try is use another JVM to execute the build and see it the problem still is there.

Finally, the fix goal of the Maven Javavoc Plugin is highly dependant on QDOX; it could be maybe some work, but maybe you can implement some test directly with that library and try to process your code to see if the problem persists.

答案2

得分: 1

假设

错误消息暗示类型解析失败(class is missing),似乎是因为插件试图解析一个 稍微 无效的路径而发生的(注意 "wrong name: com/amazonaws/mws/feeds/model//ReportInfo" 中的双斜杠)。

问题识别

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

[DEBUG] 分析 com.amazonaws.mws.feeds.model.GetFeedSubmissionListByNextTokenResult
[INFO] 保存更改到 com.amazonaws.mws.feeds.model.GetFeedSubmissionListByNextTokenResult
[DEBUG] 分析 com.amazonaws.mws.feeds.model.UpdateReportAcknowledgementsResult
[INFO] ------------------------------------------------------------------------
[INFO] 构建失败
[INFO] ------------------------------------------------------------------------ 

成功处理的最后一个类是 GetFeedSubmissionListByNextTokenResult(处理顺序不总是相同,但这不相关),但 UpdateReportAcknowledgementsResult 失败了。现在我们可以专注于这个类。

对堆栈跟踪的进一步调查显示,异常发生在插件修复(替换)链接标签时(熟悉的 {@link ClassName} javadoc 标签):

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

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

根本原因

真正的问题显而易见,例如在 UpdateReportAcknowledgementsResult:147 中:

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

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

我猜这些点可能是在大规模查找和替换操作期间出现的错误。我曾经的一个“朋友”也曾犯过类似的错误...

英文:

Asumption

The error message implies that a type resolution failed (class is missing) and this seems to happen because the plugin tries to resolve a slightly invalid path (notice the double slashes in "wrong name: com/amazonaws/mws/feeds/model//ReportInfo").

Identifying the problem

I started with mvn -X javadoc:fix in order to enable debuging. The output was very helpful:

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

The last class successfully processed was GetFeedSubmissionListByNextTokenResult (the processing order is not always the same but that's irrelevant) but UpdateReportAcknowledgementsResult failed. Now we can focus on this class.

Further investigation on the stack trace revealed that the exception occurred while the plugin was fixing (replacing) link tags (the familiar {@link ClassName} javadoc tag):

    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)

Now we know what to search for in that class.

Root cause

The real problem was immediately obvious, for example at UpdateReportAcknowledgementsResult:147

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

That dot before the class name is not correctly handled in QDOX's TypeResolver. Once I removed all {@link .X} occurrences, the plugin was executed successfully.

My guess is that these dots were put there by mistake during a massive find-and-replace operation. A friend of mine did something similar once...

huangapple
  • 本文由 发表于 2020年8月2日 19:08:08
  • 转载请务必保留本文链接:https://go.coder-hub.com/63215279.html
匿名

发表评论

匿名网友

:?: :razz: :sad: :evil: :!: :smile: :oops: :grin: :eek: :shock: :???: :cool: :lol: :mad: :twisted: :roll: :wink: :idea: :arrow: :neutral: :cry: :mrgreen:

确定