Как записать Javadoc свойств?
Я часто оказываюсь с дилеммой при записи javadoc для свойств/участников "простого" класса POJO, содержащего только свойства и методов get и методы set (стиль DTO)....
1) Запишите javadoc для свойства
или...
2) Запишите javadoc для метода get
Если я запишу javadoc для свойства, то мой IDE (Eclipse) (естественно) не будет в состоянии отобразить это когда я более поздний доступ POJO через завершение кода. И нет никакого стандарта javadoc тега, который позволяет мне связать метода-get-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 описание свойства для Ваших методов get - не имея необходимость копировать комментарий Javadoc.
На данный момент я полагаю, что создание моей практики к только документирует методов get а не свойства. Но это не походит на лучшее решение...
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" , и скопируйте предложение со строчной буквой «т». Затем я использую @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 - просто первая буква должна быть не заглавной / рекапитализированной при вставке.
Вы можете включить частные члены при генерации 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;
}
}