Как документировать параметры записи Java?

Question

Как можно документировать параметры записи Java? Я имею в виду параметры, которые в конечном итоге становятся параметрами конструктора, полями класса.

Я попытался:

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

но флаги IntelliJ IDEA @params как ошибка. Я не смог найти в Интернете пример того, как это должно работать. Ближайшее обсуждение, которое я нашел, - https://bugs.openjdk.java.net/browse/JDK-8225055.

Я нашел несколько модульных тестов в JDK, которые, похоже, предполагают, что это должно работать. Возможно, это ошибка IDE?

Я использую OpenJDK 14+36-1461, IDEA 2020.1.

Я на всякий случай подал отчет об ошибке против IDEA.

Answer 1

Ошибка / отсутствие функции IntelliJ

Использование встроенного инструмента JDK для javadoc с версией 14-ea и выше, я мог легко создать Javadoc для record.

Для этого используется команда \

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

Так что в IntelliJ наверняка чего-то не хватало. (Поскольку опция "Добавить Javadoc" также не включает компоненты.)

Я должен добавить с точки зрения разработки IntelliJ, конечно, поскольку функция предварительного просмотра, приоритизирующая работу, посвященную ей, в такой степени, также является вызовом, к которому следует относиться осторожно.

Answer 2

Вы также можете переопределить созданные методы записи и предоставить по ним документацию:

      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;
  }
}

Важно помнить, что это пример. Если документация ваших геттеров просто @return the method nameдобавление документации javadoc практически не дает никакой ценности (кроме, возможно, требований, налагаемых вашей рабочей средой).