38

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.

Naman
  • 27,789
  • 26
  • 218
  • 353
Gili
  • 86,244
  • 97
  • 390
  • 689

2 Answers2

15

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
Naman
  • 27,789
  • 26
  • 218
  • 353
  • 1
    Update - Apparently, [the bug reported](https://youtrack.jetbrains.com/issue/IDEA-238925) by the asker is accepted to be Fixed on the tracker. – Naman Apr 29 '20 at 08:12
  • 1
    Update , the bug appears to be Fixed in build 202.3267, current 201.8538.31 was released on 7 July and java doc still does not work on record. I will try the 2020.2 EAP to validate if fixed. – OctavioCega Jul 16 '20 at 08:37
2

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

A248
  • 690
  • 7
  • 17