maven-javadoc-plugin:如何动态更新模块路径

Question

我有一个Java (11.0.7) Maven (3.0.6)多模块项目，它包含以下模块声明：

<modules>
    <module>jdrum-commons</module>
    <module>jdrum-datastore-base</module>
    <module>jdrum-datastore-simple</module>
    <module>jdrum</module>
</modules>

每个Maven模块都包含一个module-info，它定义了必要的需求和导出，以限制访问和可见性。

因此，jdrum-datastore-simple有一些我在jdrum的测试中重用的测试实用工具类，通过下面的代码片段配置jdrum的配置中的偏火插件，我就可以对整个项目进行打包，而不会出现任何问题。

<build>
    <plugins>
        <plugin>
            <artifactId>maven-surefire-plugin</artifactId>
            <configuration>
                <argLine>
                    <!-- Allow the unnamed module access to the tests at test-time -->
                    --add-opens jdrum/at.rovo.drum.impl=ALL-UNNAMED
                    --illegal-access=deny
                </argLine>
            </configuration>
        </plugin>
    </plugins>
</build>

在父级POM中，我还通过site参数配置了报表的生成，该参数还生成相应项目的Javadoc。包含javadoc的JAR的配置和作为报告一部分的Javadoc生成的配置都是相同的，如下所示：

<!-- Generate Javadoc while reporting -->
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>3.2.0</version>
    <inherited>true</inherited>
    <configuration>
        <verbose>true</verbose>
        <source>${maven.compiler.source}</source>
        <show>protected</show>
        <failOnWarnings>false</failOnWarnings>
        <release>${maven.compiler.release}</release>
        <stylesheet>java</stylesheet>
    </configuration>
    <reportSets>
        <reportSet>
            <id>html</id>
            <reports>
                <report>javadoc</report>
            </reports>
        </reportSet>
    </reportSets>
</plugin>

作为package步骤的一部分，Javadoc生成作为输出生成project-version-javadoc.jar，作为输出成功，jdrum-datastore-simple依赖项及其测试都成功，仅在测试时包括：

<!-- Test data store to use for testing -->
<dependency>
    <groupId>at.rovo</groupId>
    <artifactId>jdrum-datastore-simple</artifactId>
    <version>${project.parent.version}</version>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>at.rovo</groupId>
    <artifactId>jdrum-datastore-simple</artifactId>
    <version>${project.parent.version}</version>
    <scope>test</scope>
    <type>test-jar</type>
</dependency>

如果我将作用域从test更改为compile或provided，那么Javadoc生成也会失败，从而产生一个错误，例如

Exit code: 1 - javadoc: error - The code being documented uses packages in the unnamed module, but the packages defined in https://github.com/RovoMe/JDrum/jdrum-datastore-simple/apidocs/ are in named modules.

据我理解，这里的问题是，jdrum-datastore-simple模块没有添加到Javadoc的模块路径中。因此，下一个逻辑步骤是以这样的方式实现将该模块添加到配置中：

<reporting>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-javadoc-plugin</artifactId>
            <configuration>
                <additionalOptions>
                    <option>--add-modules</option>
                    <option>jdrum.datastore.simple</option>
                </additionalOptions>
            </configuration>
        </plugin>
    </plugins>
</reporting>

这将将jdrum-datastore-simple模块添加到Javadoc配置字符串中，可以在jdrum/target/site/apidocs/options文件中看到该配置字符串，该文件现在包含

...
--add-modules
jdrum.datastore.simple
...

进入。在进一步分析生成的options文件时，显然模块路径遗漏了对实际JAR文件的引用，从而导致Javadoc生成，因此，由于Javadoc无法定位定义的模块，Maven进程失败。如果我更新该选项文件并将路径添加到缺少的JAR文件中，然后只执行一个mvn package site，整个过程就会成功，一切都很好(就像仅调用位于目标/站点/apidocs文件夹中的javadoc.bat一样)。

现在，为了使整个过程更加动态，我想添加或更新模块路径。但是，maven-javadoc-plugin不允许这样做。因此，我又为--module-path添加了一个maven-javadoc选项，并添加了一个包含整个路径的选项条目。对于整个路径，我指的是指向每个依赖项的路径，而不仅仅是指向jdrum-datastore-simple的路径。这也有效，但是由于硬编码到各自JAR文件的路径，因此其他用户现在无法使用该项目，除非他们具有我使用的相同的系统和路径结构。为了解决这个问题，我迅速地在模块路径中的各个模块上用${settings.localRepository}和${project.parent.basedir}属性替换了相应的路径结构。不幸的是，Javadoc在它接受的路径结构上相当挑剔，而且在我的Windows机器上，Maven确实返回了一个以C:\Users\...开头的路径结构，这是Javadoc无法处理的。但是，如果路径结构看起来像C:/Users/...，那么Javadoc的值很好。

在进一步的研究中，我偶然发现了这条线，它建议使用Maven的build-helper-maven-plugin为M2存储库定义新的属性，并使用内置的reg功能将\字符替换为/。但是，添加一个配置，例如

<plugin>
    <groupId>org.codehaus.mojo</groupId>
    <artifactId>build-helper-maven-plugin</artifactId>
    <version>3.1.0</version>
    <executions>
        <execution>
            <id>replace-local-repo-characters</id>
            <goals>
                <goal>regex-property</goal>
            </goals>
            <configuration>
                <name>tag.m2repo</name>
                <value>${settings.localRepository}</value>
                <regex>\\</regex>
                <replacement>/</replacement>
                <failIfNoMatch>false</failIfNoMatch>
            </configuration>
        </execution>
        <execution>
            <id>replace-local-path-characters</id>
            <goals>
                <goal>regex-property</goal>
            </goals>
            <configuration>
                <name>tag.basedir</name>
                <value>${project.parent.basedir}</value>
                <regex>\\</regex>
                <replacement>/</replacement>
                <failIfNoMatch>false</failIfNoMatch>
            </configuration>
        </execution>
    </executions>
</plugin>

相反，使用引入的标记根本不起作用，因为Maven抱怨提供的值无效。如果我使用$\{settings.localRepository}，那么Maven对提供的值很好，但是在最后的选项文件中，没有更新实际settings.localRepository的值，而是更新了提供的字符串本身，最后得到了类似于Javadoc无法解决的$/{settings.localRepository}/org/slf4j/...，因此仍然遗漏了jdrum-datastore-simple依赖项的正确位置。

那么，如何将路径添加到Maven -javadoc-plugin在生成的选项文件中定义的模块路径中，从而使Maven实际上能够生成整个报表？

Answer 1

使用java11 Update 9 (可能也使用更新8；而不是测试)，maven- Javadoc插件似乎能够为多模块项目正确生成Javadoc，而无需更改模块路径。

对于那些感兴趣的人来说，实际的Maven POM是什么样的：

• 亲本POM
• 共享模块的POM
• 共享和消费模块的POM
• 消费模块的POM