CODEWITHSUNDEEP
javaintellij-ideajavadocjava-14java-record
Gili
Gili

Reputation: 90150

How to document Java Record parameters?

How is one supposed to document Java Record parameters? I am referring to the parameters that end up becoming constructor parameters, class fields.

I tried:

/**
 * @param name the name of the animal
 * @param age the age of the animal
 */
public record Animal(String name, int age)
{
}

but IntelliJ IDEA flags @params as an error. I couldn't find an online example of how this is supposed to work. The closest discussion I found is https://bugs.openjdk.java.net/browse/JDK-8225055.

I found some unit tests in the JDK that seem to imply this should be working. Perhaps this is an IDE bug?

I am using OpenJDK 14+36-1461, IDEA 2020.1.

I filed a bug report against IDEA just in case.

Upvotes: 50

Views: 9877

Answers (4)

Thorsten Langer
Thorsten Langer

Reputation: 1

I propose

public record Animal(String name, int age)
{
    /**
     * @param name the name of the animal
     * @param age the age of the animal 
     */
    public Animal { }
}

It brings the doc to the parameters of the compact constructor, which is helpful as well.

Upvotes: -1

mipo256
mipo256

Reputation: 3214

Technically, the way the author is documenting constructor parameters in JEP 395 records is correct. There was a discussion about this in openjdk issue. If you experience the same behavior in IntelliJ, then you need to update to at least IntelliJ 2020.2, where the fix patch was ported.

Upvotes: 3

A248
A248

Reputation: 804

You can also override the generated record methods and provide documentation on them:

public record Animal(String name, int age) {

  /**
   * The name of the animal
   *
   * @return the name
   */
  public String name() {
    return name;
  }

  /**
   * Gets the age of the animal
   *
   * @return the age
   */
  public int age() {
    return age;
  }
}

It's important to remember that this is an example. If the documentation of your getters is just @return the method name, adding a javadoc provides little to no value (besides possibly a requirement imposed by your work environment).

Upvotes: 3

Naman
Naman

Reputation: 32028

IntelliJ Bug / Missing Feature

Using the in-built JDK tool for javadoc with the version 14-ea and above, I could easily generate Javadoc for a record.

enter image description here

The command used for the same is \

/jdk-14.jdk/.../javadoc --release=14 --enable-preview .../src/main/java/.../CityRecord.java

So this would certainly be something missing in IntelliJ. (Since the 'Add Javadoc' option also doesn't include the components.)

I must add from the IntelliJ development point of view, of course as a preview feature prioritizing the work dedicated towards it to such an extent is also a call that must be taken carefully.

Update: I could verify that this has been fixed with the latest update from IntelliJ:

IntelliJ IDEA 2020.2.2 Preview (Community Edition)
Build #IC-202.7319.5, built on September 1, 2020
Runtime version: 11.0.8+10-b944.31 x86_64

Upvotes: 18

Related Questions