如何在不重新生成 javadoc 的情况下聚合 maven 子项目 javadoc 输出

Question

我有一个较大的多模块 Maven 构建。我需要为所有模块生成 javadoc 并生成一个“聚合的”javadoc 结果，我可以将其部署到一个盒子以供用户使用。

在我尝试实现具有特定功能和要求的自定义 taglet 之前，我确实让这个工作得很好很长一段时间，这使得它的制作变得更加复杂。

所有子模块都继承了一个不是聚合器 pom 的父 pom。在那个父 pom 中，我定义了 maven-javadoc-plugin。这是我添加自定义 taglet 之前的样子：

        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-javadoc-plugin</artifactId>
            <version>2.10.4</version>
            <configuration>
                <additionalparam>-Xdoclint:none</additionalparam>
                <bottom>Unified Service Layer - bottom</bottom>
                <doctitle>Unified Service Layer - title</doctitle>
                <footer>Unified Service Layer - footer</footer>
                <groups></groups>
                <header>Unified Service Layer - header</header>
                <level>public</level>
                <packagesheader>Unified Service Layer - packagesheader</packagesheader>
                <top>Unified Server Layer - top</top>
                <windowtitle>Unified Service Layer - windowtitle</windowtitle>
            </configuration>
            <executions>
                <execution>
                    <id>module-javadoc-jar</id>
                    <phase>package</phase>
                    <goals>
                        <goal>jar</goal>
                    </goals>
                    <configuration>
                        <show>protected</show>
                        <detectLinks>false</detectLinks>
                    </configuration>
                </execution>
                <execution>
                    <id>aggregated-documentation</id>
                    <phase>package</phase>
                    <inherited>false</inherited>
                    <goals>
                        <goal>aggregate-jar</goal>
                    </goals>
                    <configuration>
                        <show>protected</show>
                        <detectLinks>false</detectLinks>
                    </configuration>
                </execution>
            </executions>
        </plugin>

有了这个，我可以构建所有模块，这些模块将生成它们自己的 javadoc（我现在知道这只是一个验证步骤，因为 aggregate-jar 不使用此输出）。我从 jenkins 调用了一个单独的步骤，该步骤在根项目中运行“javadoc:aggregate-jar”，它生成了我部署的聚合 javadoc jar。

同样，到目前为止，这一直运行良好。

我实现了一个自定义 javadoc taglet，它需要访问与其包含的源文件关联的 Class 对象。通过将以下内容添加到上面的配置中，我得到了这个工作，至少在单个模块构建中：

                <taglets>
                    <taglet>
                        <tagletClass>com.att.det.taglet.ValidationConstraintsTaglet</tagletClass>
                    </taglet>
                    <taglet>
                        <tagletClass>com.att.det.taglet.ValidationConstraintsCombinedTaglet</tagletClass>
                    </taglet>
                </taglets>
                <tagletArtifacts>
                    <tagletArtifact>
                        <groupId>com.att.detsusl.taglets</groupId>
                        <artifactId>validationJavadocTaglet</artifactId>
                        <version>0.0.1-SNAPSHOT</version>
                    </tagletArtifact>
                </tagletArtifacts>

为了让 taglet 能够访问类文件，我必须在每个子项目 pom.xml 中添加一个最小的插件配置，如下所示：

        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-javadoc-plugin</artifactId>
            <configuration>
                <tagletArtifacts combine.children="append">
                    <tagletArtifact>
                        <groupId>com.att.detsusl</groupId>
                        <artifactId>artifact-name</artifactId>
                        <version>${current.pom.version}</version>
                    </tagletArtifact>
                </tagletArtifacts>
            </configuration>
        </plugin>

通过这些最小的更改，我可以在每个模块中运行构建，生成 javadoc，并检查每个模块中生成的 javadoc 输出，验证一切是否正常。

但是，问题是，当我在根项目中运行“javadoc:aggregate-jar”时，所有已经构建的输出都被忽略了。它为所有子项目重新运行 javadoc 生成，同时忽略每个子项目 pom.xml 文件中附加的 tagletArtifacts 列表。结果，当它尝试获取类文件时，我得到了 ClassNotFound 错误。

我可以通过将所有子项目 GAV 放入顶级“tagletArtifacts”列表来“解决”这个问题，但我绝对不想这样做。我喜欢在子项目 pom.xml（使用 combine.children="append"）中指定它以使其工作的能力。

我需要的是所有子项目的整体 javadoc 包，taglet 能够访问类文件，而无需强制父 pom 了解其所有子项目。我该怎么做？

Answer 1

我在所有汇总目标方面都面临同样的问题。我检查了maven-javadoc-plugin 的源代码，结果发现聚合工作通过遍历子模块和收集源文件，仅此而已，因此完全忽略了子模块中指定的任何表单配置。

在执行期间，每个子模块都被完全忽略： source

if ( isAggregator() && !project.isExecutionRoot() ) {
    return;
}

在收集源文件的过程中会遍历子模块：source

if ( isAggregator() && project.isExecutionRoot() ) {
    for ( MavenProject subProject : reactorProjects ) {
        if ( subProject != project ) {
            List<String> sourceRoots = getProjectSourceRoots( subProject );

所以目前没有办法做到这一点。

这也不容易解决，因为整个插件通过对实际 javadoc 工具的单个调用来工作。如果您还想尊重子模块中的设置，则必须合并它们的配置块。虽然这适用于您使用 tagletArtifacts 的情况，但它不适用于您可以指定的所有设置，例如任何形式的过滤器，因此不能以通用方式完成。