Как написать 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's javadoc
   */
  public String getName() {  
    return name;  
  }  

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

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

Вы можете включить частные члены при создании документации Javadoc (используя -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;
    }
}

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Аннотацию создает геттер для каждого частного поля и прикрепить Javadoc к нему.

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

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

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

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

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

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

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

/**
 * 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 - просто первая буква должна быть не заглавной / рекапитализированной при вставке.

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

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