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.

Solution

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