Why mvn javadoc:fix shows success while in the same project mvn javadoc:javadoc fails afterwards?

Question

I am trying to fix existing Javadocs into the project .

I am running mvn javadoc:fix . It executes successfully BUT doesn't fix some of the Javadocs.

Configuration of Maven Javadoc plugin:

[DEBUG] Configuring mojo org.apache.maven.plugins:maven-javadoc-plugin:3.2.0:fix from plugin realm ClassRealm[plugin>org.apache.maven.plugins:maven-javadoc-plugin:3.2.0, parent: jdk.internal.loader.ClassLoaders$AppClassLoader@799f7e29]
[DEBUG] Configuring mojo 'org.apache.maven.plugins:maven-javadoc-plugin:3.2.0:fix' with basic configurator -->
[DEBUG]   (f) comparisonVersion = (,1.2.0)
[DEBUG]   (f) defaultSince = 1.2.0
[DEBUG]   (f) defaultVersion = $Id: $Id
[DEBUG]   (f) encoding = UTF-8
[DEBUG]   (f) fixClassComment = true
[DEBUG]   (f) fixFieldComment = true
[DEBUG]   (f) fixMethodComment = true
[DEBUG]   (f) fixTags = all
[DEBUG]   (f) ignoreClirr = false
[DEBUG]   (f) includes = **\/*.java
[DEBUG]   (f) level = protected
[DEBUG]   (f) localRepository =       id: local
      url: file:///Users/dmytro/.m2/repository/
   layout: default
snapshots: [enabled => true, update => always]
 releases: [enabled => true, update => always]

[DEBUG]   (f) outputDirectory = /Users/dmytro/Documents/projects/amazon-mws-feeds-maven/src/main/java
[DEBUG]   (f) project = MavenProject: com.github.chameleontartu:amazon-mws-feeds-maven:1.2.0 @ /Users/dmytro/Documents/projects/amazon-mws-feeds-maven/pom.xml
[DEBUG]   (f) removeUnknownThrows = true
[DEBUG]   (f) session = org.apache.maven.execution.MavenSession@2f1ea80d
[DEBUG]   (f) settings = org.apache.maven.execution.SettingsAdapter@2ce56d1c
[DEBUG] -- end configuration --

Part of the output for mvn javadoc:javadoc :

[DEBUG] Configuring mojo org.apache.maven.plugins:maven-javadoc-plugin:3.2.0:javadoc from plugin realm ClassRealm[plugin>org.apache.maven.plugins:maven-javadoc-plugin:3.2.0, parent: jdk.internal.loader.ClassLoaders$AppClassLoader@799f7e29]
[DEBUG] Configuring mojo 'org.apache.maven.plugins:maven-javadoc-plugin:3.2.0:javadoc' with basic configurator -->
[DEBUG]   (f) applyJavadocSecurityFix = true
[DEBUG]   (f) author = true
[DEBUG]   (f) bootclasspathArtifacts = []
[DEBUG]   (f) bottom = Copyright © {inceptionYear}–{currentYear} {organizationName}. All rights reserved.
[DEBUG]   (f) breakiterator = false
[DEBUG]   (f) debug = false
[DEBUG]   (s) destDir = apidocs
[DEBUG]   (f) detectJavaApiLink = true
[DEBUG]   (f) detectLinks = false
[DEBUG]   (f) detectOfflineLinks = false
[DEBUG]   (f) docencoding = UTF-8
[DEBUG]   (f) docfilessubdirs = false
[DEBUG]   (f) docletArtifact = groupId = 'null'
artifactId = 'null'
version = 'null'
[DEBUG]   (f) docletArtifacts = []
[DEBUG]   (f) doctitle = Amazon MWS :: Feeds 1.2.0 API
[DEBUG]   (f) encoding = UTF-8
[DEBUG]   (f) failOnError = true
[DEBUG]   (f) failOnWarnings = false
[DEBUG]   (f) includeDependencySources = false
[DEBUG]   (f) includeTransitiveDependencySources = false
[DEBUG]   (f) isOffline = false
[DEBUG]   (f) javaApiLinks = {}
[DEBUG]   (f) javadocDirectory = /Users/dmytro/Documents/projects/amazon-mws-feeds-maven/src/main/javadoc
[DEBUG]   (f) javadocOptionsDir = /Users/dmytro/Documents/projects/amazon-mws-feeds-maven/target/javadoc-bundle-options
[DEBUG]   (f) keywords = false
[DEBUG]   (f) links = []
[DEBUG]   (f) linksource = false
[DEBUG]   (f) localRepository =       id: local
      url: file:///Users/dmytro/.m2/repository/
   layout: default
snapshots: [enabled => true, update => always]
 releases: [enabled => true, update => always]

[DEBUG]   (f) mojo = org.apache.maven.plugins:maven-javadoc-plugin:3.2.0:javadoc {execution: default-cli}
[DEBUG]   (f) nocomment = false
[DEBUG]   (f) nodeprecated = false
[DEBUG]   (f) nodeprecatedlist = false
[DEBUG]   (f) nohelp = false
[DEBUG]   (f) noindex = false
[DEBUG]   (f) nonavbar = false
[DEBUG]   (f) nooverview = false
[DEBUG]   (f) nosince = false
[DEBUG]   (f) notimestamp = false
[DEBUG]   (f) notree = false
[DEBUG]   (f) offlineLinks = []
[DEBUG]   (f) old = false
[DEBUG]   (f) outputDirectory = /Users/dmytro/Documents/projects/amazon-mws-feeds-maven/target/apidocs
[DEBUG]   (f) overview = /Users/dmytro/Documents/projects/amazon-mws-feeds-maven/src/main/javadoc/overview.html
[DEBUG]   (f) project = MavenProject: com.github.chameleontartu:amazon-mws-feeds-maven:1.2.0 @ /Users/dmytro/Documents/projects/amazon-mws-feeds-maven/pom.xml
[DEBUG]   (f) quiet = true
[DEBUG]   (f) reactorProjects = [MavenProject: com.github.chameleontartu:amazon-mws-feeds-maven:1.2.0 @ /Users/dmytro/Documents/projects/amazon-mws-feeds-maven/pom.xml]
[DEBUG]   (s) reportOutputDirectory = /Users/dmytro/Documents/projects/amazon-mws-feeds-maven/target/site/apidocs
[DEBUG]   (f) resourcesArtifacts = []
[DEBUG]   (f) serialwarn = false
[DEBUG]   (f) session = org.apache.maven.execution.MavenSession@7d78f3d5
[DEBUG]   (f) settings = org.apache.maven.execution.SettingsAdapter@a4b5ce3
[DEBUG]   (f) show = protected
[DEBUG]   (f) skip = false
[DEBUG]   (f) source = 1.6
[DEBUG]   (f) sourceDependencyCacheDir = /Users/dmytro/Documents/projects/amazon-mws-feeds-maven/target/distro-javadoc-sources
[DEBUG]   (f) splitindex = false
[DEBUG]   (f) staleDataPath = /Users/dmytro/Documents/projects/amazon-mws-feeds-maven/target/maven-javadoc-plugin-stale-data.txt
[DEBUG]   (f) stylesheet = java
[DEBUG]   (f) tagletArtifact = groupId = 'null'
artifactId = 'null'
version = 'null'
[DEBUG]   (f) tagletArtifacts = []
[DEBUG]   (f) taglets = []
[DEBUG]   (f) tags = []
[DEBUG]   (f) use = true
[DEBUG]   (f) useStandardDocletOptions = true
[DEBUG]   (f) validateLinks = false
[DEBUG]   (f) verbose = false
[DEBUG]   (f) version = true
[DEBUG]   (f) windowtitle = Amazon MWS :: Feeds 1.2.0 API
[DEBUG] -- end configuration --
[DEBUG] Found Java API link: https://docs.oracle.com/javase/6/docs/api/
[INFO] No previous run data found, generating javadoc.
[DEBUG] /Users/dmytro/.sdkman/candidates/java/current/bin/javadoc @options @packages
[INFO] 
100 errors
[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  4.642 s
[INFO] Finished at: 2020-08-06T15:55:56+02:00
[INFO] ------------------------------------------------------------------------
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-javadoc-plugin:3.2.0:javadoc (default-cli) on project amazon-mws-feeds-maven: An error has occurred in Javadoc report generation: 
[ERROR] Exit code: 1 - /Users/dmytro/Documents/projects/amazon-mws-feeds-maven/src/main/java/com/amazonaws/mws/feeds/model/GetReportRequestCountResponse.java:13: error: bad use of '>'
[ERROR]  * <complexType>
[ERROR]                   ^
[ERROR] /Users/dmytro/Documents/projects/amazon-mws-feeds-maven/src/main/java/com/amazonaws/mws/feeds/model/GetReportRequestCountResponse.java:14: error: bad use of '>'
[ERROR]  *   <complexContent>
[ERROR]                        ^
[ERROR] /Users/dmytro/Documents/projects/amazon-mws-feeds-maven/src/main/java/com/amazonaws/mws/feeds/model/GetReportRequestCountResponse.java:15: error: bad use of '>'
[ERROR]  *     <restriction base="{http://www.w3.org/2001/XMLSchema}anyType">
[ERROR]                                                                        ^
[ERROR] /Users/dmytro/Documents/projects/amazon-mws-feeds-maven/src/main/java/com/amazonaws/mws/feeds/model/GetReportRequestCountResponse.java:16: error: bad use of '>'
[ERROR]  *       <sequence>
[ERROR]                      ^
[ERROR] /Users/dmytro/Documents/projects/amazon-mws-feeds-maven/src/main/java/com/amazonaws/mws/feeds/model/GetReportRequestCountResponse.java:17: error: bad use of '>'
[ERROR]  *         <element ref="{http://mws.amazonaws.com/doc/2009-01-01/}GetReportRequestCountResult"/>
[ERROR]                                                                                                    ^
[ERROR] /Users/dmytro/Documents/projects/amazon-mws-feeds-maven/src/main/java/com/amazonaws/mws/feeds/model/GetReportRequestCountResponse.java:18: error: bad use of '>'
[ERROR]  *         <element ref="{http://mws.amazonaws.com/doc/2009-01-01/}ResponseMetadata"/>
[ERROR]                                                                                         ^
[ERROR] /Users/dmytro/Documents/projects/amazon-mws-feeds-maven/src/main/java/com/amazonaws/mws/feeds/model/GetReportRequestCountResponse.java:19: error: bad use of '>'
[ERROR]  *       </sequence>
[ERROR]                       ^
[ERROR] /Users/dmytro/Documents/projects/amazon-mws-feeds-maven/src/main/java/com/amazonaws/mws/feeds/model/GetReportRequestCountResponse.java:20: error: bad use of '>'
[ERROR]  *     </restriction>
[ERROR]                        ^
[ERROR] /Users/dmytro/Documents/projects/amazon-mws-feeds-maven/src/main/java/com/amazonaws/mws/feeds/model/GetReportRequestCountResponse.java:21: error: bad use of '>'
[ERROR]  *   </complexContent>
[ERROR]                         ^
[ERROR] /Users/dmytro/Documents/projects/amazon-mws-feeds-maven/src/main/java/com/amazonaws/mws/feeds/model/GetReportRequestCountResponse.java:22: error: bad use of '>'
[ERROR]  * </complexType>
[ERROR]                    ^
[ERROR] /Users/dmytro/Documents/projects/amazon-mws-feeds-maven/src/main/java/com/amazonaws/mws/feeds/model/GetReportRequestCountResponse.java:25: error: self-closing element not allowed
[ERROR]  * <p/>
[ERROR]    ^

On similar projects, before it worked I just don't understand what am I doing wrong?

Maven/Java details:

$ mvn --version
Apache Maven 3.6.1 (d66c9c0b3152b2e69ee9bac180bb8fcc8e6af555; 2019-04-04T21:00:29+02:00)
Maven home: /Users/dmytro/.sdkman/candidates/maven/current
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"

Answer 1

AWS most likely uses JAXB to generate your web service model.

JAXB has an issue consisting in that it does not correctly escape the > symbol with gt; when generating the Java artifacts.

Before JDK 1.8, this was not a problem.

But, since JDK 8, the javadoc tool includes doclint . This new part will check your code for compliance with the HTML 4.01 specification and will generate errors for every nonconformity it finds.

Among others, it will report the error of the above-mentioned problem and other non-conformities that cause the javadoc:javadoc goal in your maven project to fail.

This excelent article explains in great detail this change in the javadoc tool.

To avoid that error, successfully generate your documentation, and deploy your artifact to Maven central, you can modify your javadoc maven plugin configuration and disable doclint :

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>${maven-javadoc-plugin.version}</version>
    <configuration>
        <attach>true</attach>
        <source>${jdk.version}</source>
        <!--                        <quiet>true</quiet>-->
        <detectOfflineLinks>false</detectOfflineLinks>
        <encoding>${project.build.sourceEncoding}</encoding>
        <doclint>none</doclint>
    </configuration>
</plugin>

Please, observe the inclusion of the <doclint> element.

You can disable doclint completely (like in the example), or limit its use to certain group s .

There is only one piece left to fit into this puzzle: why doesn't the javadoc: fix goal fix those errors. Honestly, I can't give you an answer: I don't know if it's a bug (I guess not) or just that the tool doesn't fix those kinds of errors. I hope someone can shed some light on the subject.