module-info.java中Javadoc @link标签无法正常工作的问题排查

1. 更新Maven Javadoc插件版本 #

JDK 11的模块化Javadoc生成需要插件支持，旧版本插件对模块化处理有缺陷。在pom.xml中指定3.2.0及以上版本的插件：

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-javadoc-plugin</artifactId>
            <version>3.5.0</version>
            <configuration>
                <failOnError>true</failOnError>
            </configuration>
        </plugin>
    </plugins>
</build>

2. 修正{@link}的引用格式 #

在module-info.java的Javadoc里，引用内部包必须加上模块名前缀，格式为{@link 模块名/包名}。假设你的模块名为myproject，写法如下：

/**
 * 模块说明，引用工具包{@link myproject/myproject.tools}
 */
module myproject {
    opens myproject.tools;
    // 其他模块声明
}

3. 确认package-info.java的正确性 #

确保myproject.tools包下的package-info.java格式无误，示例：

/**
 * 工具包的功能说明
 */
package myproject.tools;

4. 给Javadoc插件添加模块化参数 #

如果更新版本后仍报错，在插件配置中添加模块路径参数，帮助插件识别项目模块结构：

<configuration>
    <additionalJOptions>
        <additionalJOption>--module-path</additionalJOption>
        <additionalJOption>${project.build.directory}/classes</additionalJOption>
    </additionalJOptions>
</configuration>

5. 清理重建项目 #

执行以下命令清理旧构建文件，重新生成Javadoc：

mvn clean javadoc:javadoc

内容的提问来源于stack exchange，提问作者dan