Java 21 Record生成Javadoc遇no @param警告，求原因与解决方法

问题 #

我正在尝试为非常简单的Java 21 Record生成Javadoc，现有代码、配置及执行情况如下：

Record代码 #

/**
 * The type Some record.
 */
public record SomeRecord(String someField) {
}

Maven pom配置 #

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <configuration>
        <outputDirectory>target/javadoc</outputDirectory>
        <reportOutputDirectory>target/javadoc</reportOutputDirectory>
        <javadocExecutable>${java.home}/bin/javadoc</javadocExecutable>
    </configuration>
</plugin>

执行的Maven命令 #

mvn clean install site -U javadoc:javadoc

执行后出现如下警告：

SomeRecord.java:6: warning: no @param for someField
[WARNING] public record SomeRecord(String someField) {
[WARNING] ^

请问这段代码存在什么问题？这个@param是什么？我记得Spring有@Param，但这个小写的@param是什么？如何才能正确生成无警告的Javadoc？

解答 #

1. 代码存在的问题 #

Javadoc工具会校验文档注释的完整性，Java Record的声明组件（此处的someField）等价于构造器参数，按照Javadoc规范，必须为这些组件添加@param注释说明其含义，否则会触发警告。

2. 区分@param和Spring的@Param #

• 小写的@param是Javadoc标准标签，用于在类、方法、构造器或Record的文档注释中描述参数的作用，是生成API文档的必要元素，仅在Javadoc生成过程中生效。
• Spring的@Param是运行时注解，主要用于MyBatis等框架中绑定SQL语句的参数名称，和Javadoc属于完全不同的技术范畴，作用场景与目的毫无关联。

3. 解决方法：补全Javadoc的@param标签 #

修改Record的文档注释，为someField添加对应的@param说明即可消除警告，示例代码如下：

/**
 * 描述该Record的业务作用，比如：存储基础数据的记录
 *
 * @param someField 描述该字段的含义，比如：用于存储特定信息的字符串字段
 */
public record SomeRecord(String someField) {
}

重新执行原Maven命令，就能生成无警告的Javadoc文档。

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