javamavenjarjavadocmaven-javadoc-plugin

Difference between Maven Javadoc Plugin javadoc:jar and javadoc:aggregate-jar


I've been using the Maven Javadoc Plugin javadoc:jar goal for years, publishing many Java artifacts to Nexus (Maven Central). Currently I'm using Maven 3.8.6 with Java 17, and org.apache.maven.plugins:maven-javadoc-plugin:3.4.1.

Today I'm reading the plugin documentation (emphasis in the documentation):

This confuses me a bit. What does the documentation mean when it refers to an "aggregator project"? Is it referring to a project using an aggregate POM, in which the parent POM lists several sub-project POMs being aggregated? Yet why would it make a difference which Maven Javadoc Plugin goal is used?

For years I have set up the Maven Javadoc Plugin in a "root POM" for all my projects. It uses the javadoc:jar goal. It sets up the plugin configuration for the child projects which inherit from it. Some of the child projects are standalone single-POM projects. Some of them are aggregate POMs. I've never had a problem doing it this way.

Should I be using the javadoc:jar goal for some projects, and the javadoc:aggregate-jar for other projects? But how could the root POM even know whether the child project is an aggregate project or not? What will break if I continue using the javadoc:jar goal for everything?

(As bonus, what is this separate javadoc:aggregate-no-fork goal?)


Solution

  • Yes, "aggregator project" refers to project aggregation. Using javadoc:jar or javadoc:aggregate-jar results in different outputs: