Як написати 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.

На сьогоднішній день я розглядаю можливість практикувати лише документування гетерів, а не властивостей. Але це не здається найкращим рішенням ...

Ви можете включити приватних членів під час створення 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;
    }
}

Ломбок - дуже зручна бібліотека для таких завдань.

@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. Тоді це виглядає так:

/**
 * 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, тому відмовився.

Зверніть увагу, що речення не завжди може починатися з Т - це лише перша буква, яку слід вставити без капіталу / докапіталізувати під час вставки.

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

Але я здогадуюсь: якщо вам потрібно пояснити, що таке someString, можливо, це `` поганий малий '' щодо вашого коду. Це може означати, що вам слід написати SomeClass, щоб набрати someString, щоб ви пояснили, що таке someString у документації SomeClass, і саме тому javadocs у getter / setter не буде необхідним.