Maven Javadoc Plugin 3.5.0：如何解决‘无法推导模块描述符’错误？

升级maven-javadoc-plugin到3.5.0版本后，执行jar目标时出现以下错误：

Execution build-javadoc-jar of goal org.apache.maven.plugins:maven-javadoc-plugin:3.5.0:jar failed:
  Unable to derive module descriptor for /.../rewrite-gradle-7.38.0.jar
  PluginSpec.class found in top-level directory (unnamed package not allowed in module)

项目未使用JPMS，且无法控制第三方依赖rewrite-gradle，需要让javadoc工具忽略模块命名规则。

可复现问题的POM代码：

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">

  <modelVersion>4.0.0</modelVersion>

  <groupId>reproducer</groupId>
  <artifactId>reproducer</artifactId>
  <version>0.1</version>

  <build>
    <pluginManagement>
      <plugins>
        <plugin>
          <artifactId>maven-compiler-plugin</artifactId>
          <version>3.11.0</version>
        </plugin>
        <plugin>
          <artifactId>maven-jar-plugin</artifactId>
          <version>3.3.0</version>
          <configuration>
            <archive>
              <manifestEntries>
                <Automatic-Module-Name>org.acme.reproducer</Automatic-Module-Name>
              </manifestEntries>
            </archive>
          </configuration>
        </plugin>
        <plugin>
          <artifactId>maven-javadoc-plugin</artifactId>
          <version>3.5.0</version><!-- Regression from 3.2.0 which did not have the problem-->
        </plugin>
      </plugins>
    </pluginManagement>
    <plugins>
      <plugin>
        <artifactId>maven-javadoc-plugin</artifactId>
        <executions>
          <execution>
            <goals>
              <goal>jar</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>

  <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>org.openrewrite.recipe</groupId>
        <artifactId>rewrite-recipe-bom</artifactId>
        <version>1.17.0</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
    </dependencies>
  </dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.openrewrite</groupId>
      <artifactId>rewrite-gradle</artifactId>
    </dependency>
  </dependencies>
</project>

有两种可行的解决方法：

方法一：强制使用类路径处理依赖 #

maven-javadoc-plugin 3.5.0默认启用模块路径模式，会尝试为依赖推导模块描述符。对于未使用JPMS的项目，可强制工具使用传统类路径模式，跳过模块相关处理：

<plugin>
  <artifactId>maven-javadoc-plugin</artifactId>
  <version>3.5.0</version>
  <configuration>
    <useModulePath>false</useModulePath>
  </configuration>
  <executions>
    <execution>
      <goals>
        <goal>jar</goal>
      </goals>
    </execution>
  </executions>
</plugin>

方法二：忽略源错误 #

若需保留模块路径模式，可添加Javadoc参数忽略未命名包这类模块相关错误：

<plugin>
  <artifactId>maven-javadoc-plugin</artifactId>
  <version>3.5.0</version>
  <configuration>
    <additionalJOptions>
      <additionalJOption>--ignore-source-errors</additionalJOption>
    </additionalJOptions>
  </configuration>
  <executions>
    <execution>
      <goals>
        <goal>jar</goal>
      </goals>
    </execution>
  </executions>
</plugin>

推荐使用方法一，它从根源上避免了模块路径相关的冲突，更契合未使用JPMS的项目场景。

内容的提问来源于stack exchange，提问作者Geoffrey De Smet