maven javadoc:fix fails to autofix docs

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.

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

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