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?

It's asking you to have something like @param someField a fancy field for some purpose in your JavaDoc. Also, it's just a warning: it should still produce the output just fine. — Generous Badger
– Generous Badger, Commented Dec 11, 2023 at 16:17
Why are you bothering with this? The whole point of javadoc is to help other people understand what the class does. Your automatically generated text will help no one. — VGR
– VGR, Commented Dec 11, 2023 at 22:30

Giorgi Tsiklauri · Accepted Answer · 2023-12-11 16:56:02Z

3

@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.

edited Dec 11, 2023 at 16:56

answered Dec 11, 2023 at 16:32

Giorgi Tsiklauri

11.5k9 gold badges59 silver badges84 bronze badges

Sign up to request clarification or add additional context in comments.

Collectives™ on Stack Overflow

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

1 Answer 1

Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

Comments

Your Answer

Sign up or log in

Post as a guest

Related