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