从依赖源聚合 Javadocs

自：2.7

考虑以下项目依赖关系图：

org.test:project-distro:0.1
  |
  |--> org.test.dep:project-A:1.0
  |    |
  |    |--> commons-lang:commons-lang:1.0
  |    |
  |    `--> commons-io:commons-io:1.0
  |
  |--> org.test.dep:project-B:1.1
  |    |
  |    `--> commons-io:commons-io:1.0
  |
  |--> org.test.dep:project-C:1.0
  |
  `--> commons-cli:commons-cli:1.0

假设您维护了一系列具有不同发布周期的项目，以及另一个项目，该项目用于将所有内容集成在一起以提供经过测试的平台，并协调其依赖关系以实现兼容性。为了生成项目发行版，您需要生成一套全面的 javadocs，其中不仅包含发行项目本身中的少量代码 - 这可能不是很有启发性 - 还包含适用于您的 javadocs其他项目，它们是分发的依赖项。

从 maven-javadoc-plugin 版本2.7开始，您可以使用includeDependencySources标志及其相关配置选项来执行此操作。使用此标志，可以在多模块构建中聚合来自其他模块的源，或者使用与项目的主要工件一起发布的源和测试源jar。还可以微调哪些依赖项的源应该被聚合，哪些被忽略。最后但同样重要的是，可以通过发布javadoc-resources和test-javadoc-resources从依赖项中包含非源 javadoc 配置和资源将工件与依赖项的主要工件捆绑在一起。

首先，让我们看看如何为依赖驱动的 javadoc 聚合奠定基础。

为聚合准备依赖​​项

依赖驱动的 javadoc 聚合通过解析包含依赖的源来工作，然后将这些源包含在项目的 javadoc 生产过程中。与 Maven 的常见做法一样，依赖源将从当前反应器中的其他模块中解析（如果它们在那里可用）。否则，插件将尝试为依赖项解析适当的源工件：主javadocs的源，测试 javadocs 的test-sources。注意：如果您的配置包含依赖项，但该依赖项的源工件不可用，则 javadoc 插件将失败。

生成这些源工件的推荐方法是maven-source-plugin。以下简单示例显示了如何生成源工件：

<project>
  [...]
  <groupId>org.test.dep</groupId>
  <artifactId>project-A</artifactId>
  [...]
  <build>
    <plugins>
      [...]
      <plugin>
        <artifactId>maven-source-plugin</artifactId>
        <version>2.1.1</version>
        <executions>
          <execution>
            <id>bundle-sources</id>
            <phase>package</phase>
            <goals>
              <!-- produce source artifact for main project sources -->
              <goal>jar-no-fork</goal>
              
              <!-- produce source artifact for project test sources -->
              <goal>test-jar-no-fork</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
  [...]
</project>

注意：如果您不打算生成包含依赖源的测试 javadocs，则可以省略上面的test-jar-no-fork目标。

此时，您的项目已准备好生成支持依赖驱动的 javadoc 聚合所需的工件。下次安装或部署项目时，您的分发项目将可以使用适当的工件。

微调包含的依赖项

统一项目的 javadocs 及其依赖项很好，但我们不要走得太远。除了您自己的上游项目，您的发行版还可能包含对外部项目的依赖项。在您的发行版中包含这些项目的 javadocs 可能不合适；链接到它们通常会更好。在任何情况下，您可能对这些外部项目没有足够的影响力来让它们产生像上面讨论的那样的源工件。在我们原来的例子中，看看最后一个直接依赖：

  
  `--> commons-cli:commons-cli:1.0

对于提供命令行执行选项的项目，这是一个非常常见的直接依赖项。但是考虑一下如果 commons-cli 不提供源jar 会发生什么：对于任何包含 commons-cli 作为直接依赖项的项目，依赖项驱动的 javadoc 聚合都会失败。为避免这种情况，您可以选择微调 javadoc 聚合过程中包含的依赖项。在您的分发项目中，为maven-javadoc-plugin添加配置，类似于以下内容：

<project>
  [...]
  <groupId>org.test</groupId>
  <artifactId>project-distro</artifactId>
  [...]
  <build>
    <plugins>
      [...]
      <plugin>
        <artifactId>maven-javadoc-plugin</artifactId>
        <version>3.0.1</version>
        <executions>
          <execution>
            <id>javadoc-jar</id>
            <phase>package</phase>
            <goals>
              <goal>jar</goal>
            </goals>
            <configuration>
              <!-- switch on dependency-driven aggregation -->
              <includeDependencySources>true</includeDependencySources>
              
              <dependencySourceExcludes>
                <!-- exclude ONLY commons-cli artifacts -->
                <dependencySourceExclude>commons-cli:*</dependencySourceExclude>
              </dependencySourceExcludes>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</project>

注意：以上配置仅排除commons-cli。如果您有多个外部依赖项，可能更容易配置包含哪些依赖项，如下所示：

  [...]
            <configuration>
              <!-- switch on dependency-driven aggregation -->
              <includeDependencySources>true</includeDependencySources>

              <dependencySourceIncludes>
                <!-- include ONLY dependencies I control -->
                <dependencySourceInclude>org.test.dep:*</dependencySourceInclude>
              </dependencySourceIncludes>
            </configuration>
  [...]

包括依赖项中的 Javadoc 资源

许多项目选择自定义它们的 javadoc 配置而不是默认值。

如果您为在这些依赖项项目中生成 javadocs 进行了自定义配置，您可能希望将这些自定义项传播到分发项目本身。为此，请使用2.7版中的新资源包和测试资源包目标javadoc插件的。这些将创建包含 javadoc 配置选项以及 ${javadocDirectory}（默认为 src/main/javadoc）或 ${tetsJavadocDirectory}（默认为 src/test/javadoc）的内容的新工件，具体取决于捆绑目标. 如果这些工件可用，则依赖驱动的聚合过程将包括它们在为您的分发生成 javadocs 时包含的内容和配置。以下示例显示了如何生成这些工件：

<project>
  [...]
  <groupId>org.test.dep</groupId>
  <artifactId>project-A</artifactId>
  <version>1.0</version>
  [...]
  <build>
    <plugins>
      [...]
      <plugin>
        <artifactId>maven-javadoc-plugin</artifactId>
        <version>3.0.1</version>
        <executions>
          <execution>
            <id>resource-bundles</id>
            <phase>package</phase>
            <goals>
              <!-- produce source artifact for main project sources -->
              <goal>resource-bundle</goal>

              <!-- produce source artifact for project test sources -->
              <goal>test-resource-bundle</goal>
            </goals>
            <configuration>
              <detectOfflineLinks>false</detectOfflineLinks>
              [...]
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
  [...]
</project>

注意：同样，如果您不需要生成测试 javadocs，您可以省略上面的test-resource-bundle目标。

注 2：配置选项detectOfflineLinks仅作为示例提供。这不是必需的。