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

Question

Я часто сталкиваюсь с дилеммой при написании 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.

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

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

Answer 2

Я делаю и то, и другое при помощи автозаполнения 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. Тогда это выглядит так:

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

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

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

Answer 4

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

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