warning: no @param for field in java 21 with javadoc

Question

I am trying to generate javadoc for very simple java 21 records.

I have this straightforward record:

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

and this 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>

And I am running this maven command:

mvn clean install site -U javadoc:javadoc

Every time, I get this:

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

What is wrong with this code? What is this @param? I recall a @Param for Spring, but @param (lower case?) How can I generate without the javadoc properly?

Answer 1

@param, in the Javadoc context, is called a Javadoc tag (sometimes referred to as JavaDoc block tags), and it is used for documenting what the particular parameter will be used of (i.e. what does it constitute in the domain). This has nothing to do with Spring's @Param.

Oracle says, that:

A doc comment is written in HTML and must precede a class, field, constructor or method declaration. It is made up of two parts -- a description followed by block tags.

With respect to warning: no @param for someField, it just says, that you don't have a description (which should be created by @param, in the JavaDoc) for the someField parameter.

Just add:

/**
 *
 * The type Some record.
 * @param someField here goes your description of someField
 */
public record SomeRecord(String someField) {
}

---

Finally, be aware, that javadoc tool will warn you about all the places where it expects some block tags but doesn't find them.