Search code examples
javaintellij-ideajavadocjava-14java-record

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.

Solution

  • 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