Как написать Javadoc свойств?

Я часто сталкиваюсь с дилеммой при написании javadoc для свойств/членов "простого" класса POJO, содержащего только свойства и геттеры и сеттеры (стиль DTO)....

1) Напишите javadoc для свойства
или...
2) Напишите javadoc для геттера

Если я напишу javadoc для свойства, моя IDE (Eclipse) не сможет отобразить это, когда я позже получаю доступ к POJO через завершение кода. И нет стандартного тега javadoc, который позволяет мне связать getter-javadoc с фактическим свойством javadoc.

Пример:

public class SomeDomainClass {

  /**
   * The name of bla bla bla
   */
  private String name;

  /**
   * @return INSERT SOME SMART JAVADOC TAG LINKING TO name javadoc
   */
  public String getName() {  
    return name;  
  }

Итак, в основном было бы интересно услышать, как другие идут на то, чтобы ваша среда Eclipse отображала описание свойства javadoc для ваших геттеров - без дублирования комментария javadoc.

На данный момент я рассматриваю возможность использования моей практики только для документирования геттеров, а не для свойств. Но это не похоже на лучшее решение...

Ответ 1

Вы можете включать частные члены при генерации Javadocs (используя -private), а затем использовать @link для ссылки на это свойство полей.

public class SomeDomainClass {
    /**
     * The name of bla bla bla
     */
    private String name;

    /**
     * {@link SomeDomainClass#name}
     */
    public String getName() {
        return name;
    }
}

В качестве альтернативы, если вы не хотите генерировать Javadoc для всех частных членов, вы можете иметь соглашение для документирования всех получателей и использовать @link на сеттерах.

public class SomeDomainClass {
    private String name;

    /**
     * The name of bla bla bla
     */
    public String getName() {
        return name;
    }

    /**
     * {@link SomeDomainClass#getName}
     */
    public void setName(String name) {
        this.name = name;
    }
}

Ответ 2

Я делаю оба, чему способствует автозаполнение Eclipse.

Сначала я документирую свойство:

/**
 * The {@link String} instance representing something.
 */
private String someString;

Затем я копирую и вставляю это в getter:

/**
 * The {@link String} instance representing something.
 */
public String getSomeString() {
    return someString;
}

С eclipse операторы @return имеют автозаполнение - поэтому я добавляю слово "Gets", строчный "t" и скопируйте предложение в нижнем регистре "t". Затем я использую @return (с автозаполнением Eclipse), вставляю предложение, а затем задерживаю T в возврате. Затем он выглядит следующим образом:

/**
 * Gets the {@link String} instance representing something.
 * @return The {@link String} instance representing something.
 */
public String getSomeString() {
    return someString;
}

Наконец, я копирую эту документацию в установщик:

/**
 * Gets the {@link String} instance representing something.
 * @return The {@link String} instance representing something.
 */
public void setSomeString(String someString) {
    this.someString = someString;
}

Затем я изменяю его и с автозаполнением Eclipse вы можете получить не только тег @param, но также имя параметра:

/**
 * Sets the {@link String} instance representing something.
 * @param someString The {@link String} instance representing something.
 */
public void setSomeString(String someString) {
    this.someString = someString;
}

Тогда, я закончил. На мой взгляд, этот шаблон делает намного проще, в конечном счете, не только напомнить себе, что означает свойство через повторение, но и облегчает добавление дополнительных комментариев к получателю и сеттеру, если вы хотите добавить сторону эффекты (такие как отсутствие нулевых свойств, поворот строк в верхний регистр и т.д.). Я исследовал создание плагина Eclipse для этой цели, но я не смог найти соответствующую точку расширения для JDT, поэтому я сдался.

Обратите внимание, что предложение может не всегда начинаться с T - оно только первая буква должна быть некапитализирована/рекапитализована при вклеивании.

Ответ 3

Lombok - очень удобная библиотека для таких задач.

@Getter
@Setter
public class Example {
    /**
     * The account identifier (i.e. phone number, user name or email) to be identified for the account you're
     * requesting the name for
     */
    private String name;
}

Это все, что вам нужно! Аннотация @Getter создает метод getter для каждого частного поля и присоединяет к нему javadoc.

PS. В библиотеке есть много интересных функций, которые вы можете проверить.

Ответ 4

Я действительно считаю это проблемой, и официальный Javadoc guide ничего не говорит об этом. С# может решить это в элегантном стиле с использованием свойств (я не код на С#, но я действительно считаю, что это хорошая функция).

Но у меня есть предположение: если вам нужно объяснить, что такое someString, возможно, это "плохой маленький" о вашем коде. Это может означать, что вы должны написать SomeClass для ввода someString, поэтому вы бы объяснили, что такое someString в документации SomeClass, и просто поэтому javadocs в getter/setter не понадобится.