Maven Javadoc 插件 javadoc:jar 和 javadoc:aggregate-jar 之间的区别

Question

多年来，我一直在使用 Maven Javadoc Plugin javadoc:jar 目标，将许多 Java 工件发布到 Nexus (Maven Central)。目前我正在使用带有 Java 17 的 Maven 3.8.6 和 org.apache.maven.plugins:maven-javadoc-plugin:3.4.1。

今天我正在阅读插件文档（文档中的重点）：

• javadoc:jar: "将 main Java code 的 Javadoc 文档捆绑在一个非聚合器项目使用标准 Javadoc 工具放入 jar 中。”
• aggregate-jar: "将主要 Java code 的 Javadoc 文档捆绑在一个聚合器使用标准 Javadoc 工具将项目放入 jar 中。”
• javadoc:aggregate-no-fork: "为Java code 生成文档聚合器项目使用标准的 Javadoc 工具。”

这让我有点困惑。当文档提到“聚合器项目”时，它是什么意思？它是指使用aggregate POM 的项目，其中父POM 列出了正在聚合的几个子项目POM？然而，为什么使用哪个 Maven Javadoc 插件目标会有所不同呢？

多年来，我为所有项目在“根 POM”中设置了 Maven Javadoc 插件。它使用javadoc:jar 目标。它为从它继承的子项目设置插件配置。一些子项目是独立的单 POM 项目。其中一些是聚合 POM。我从来没有遇到过这样的问题。

我是否应该将javadoc:jar 目标用于某些项目，而将javadoc:aggregate-jar 用于其他项目？但是根 POM 怎么可能知道子项目是否是聚合项目呢？如果我继续使用javadoc:jar 目标来处理所有事情，会出现什么问题？

（作为奖励，这个单独的javadoc:aggregate-no-fork 目标是什么？）

Answer 1

是的，“聚合器项目”指的是project aggregation。使用 javadoc:jar 或 javadoc:aggregate-jar 会产生不同的输出：

• 在父级上运行javadoc:jar 会在所有模块上递归执行，如您在输出中所见：

  [INFO] Building parent 0.0.0-SNAPSHOT                                     [1/3]
  ...
  [INFO] Not executing Javadoc as the project is not a Java classpath-capable package
  ...
  [INFO] Building module1 0.0.0-SNAPSHOT                                    [2/3]
  ...
  [INFO] Building jar: /module1/target/module1-0.0.0-SNAPSHOT-javadoc.jar
  ...
  [INFO] Building module2 0.0.0-SNAPSHOT                                    [3/3]
  ...
  [INFO] Building jar: /module2/target/module2-0.0.0-SNAPSHOT-javadoc.jar
  [INFO] ------------------------------------------------------------------------
  [INFO] Reactor Summary for parent 0.0.0-SNAPSHOT:
  [INFO] 
  [INFO] parent ............................................. SUCCESS [  0.942 s]
  [INFO] module1 ............................................ SUCCESS [  1.154 s]
  [INFO] module2 ............................................ SUCCESS [  1.126 s]
  [INFO] ------------------------------------------------------------------------
  [INFO] BUILD SUCCESS
  

  单独的 Javadoc 输出在每个模块的 target 文件夹中创建，并捆绑到单独的 JAR 中。

  运行javadoc:jar只要在使用--non-recursive 的父级上不会输出任何内容。

• 另一方面，javadoc:aggregate-jar 的执行运行只要在父母上：

  [INFO] Building parent 0.0.0-SNAPSHOT                                     [1/3]
  ...
  [INFO] >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
  [INFO] Forking module1 0.0.0-SNAPSHOT
  [INFO] >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
  ...
  [INFO] >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
  [INFO] Forking module2 0.0.0-SNAPSHOT
  [INFO] >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
  ...
  [INFO] Building jar: /target/parent-0.0.0-SNAPSHOT-javadoc.jar
  [INFO] ------------------------------------------------------------------------
  [INFO] Reactor Summary for parent 0.0.0-SNAPSHOT:
  [INFO] 
  [INFO] parent ............................................. SUCCESS [  2.971 s]
  [INFO] module1 ............................................ SKIPPED
  [INFO] module2 ............................................ SKIPPED
  

  Javadoc 仅在父级/target/apidocs 的一个位置创建，并捆绑到一个 JAR 中。

  模块的 Javadoc 插件被跳过，但父执行创建分叉构建，为每个模块执行 compile 阶段。

• 在父级上运行 javadoc:aggregate-no-fork 不会创建分叉构建，而是在生成 Javadocs 的每个模块上递归运行...

  [INFO] Building parent 0.0.0-SNAPSHOT                                     [1/3]
  ...
  [INFO] No previous run data found, generating javadoc.
  ...
  [INFO] Building module1 0.0.0-SNAPSHOT                                    [2/3]
  ...
  [INFO] No previous run data found, generating javadoc.
  ...
  [INFO] Building module2 0.0.0-SNAPSHOT                                    [3/3]
  ...
  [INFO] No previous run data found, generating javadoc.
  [INFO] ------------------------------------------------------------------------
  [INFO] Reactor Summary for parent 0.0.0-SNAPSHOT:
  [INFO] 
  [INFO] parent ............................................. SUCCESS [  1.909 s]
  [INFO] module1 ............................................ SUCCESS [  1.082 s]
  [INFO] module2 ............................................ SUCCESS [  0.991 s]
  

  ...并将它们聚合到父级的 /target/site/apidocs 中。

  与前面的命令相比，没有创建 JAR。