Для функций, которые не изменяют состояние экземпляра, комментарий javadoc для метода часто тот же или очень похожий, что и для тега @return-tag в Java-API.
boolean Collection.isEmpty()
Теперь я пишу javadoc для многих простых методов, таких как getExpression(), где у меня такая же проблема. Должен ли я делать это как в API или оставить его?
Из рекомендации Oracle Как написать комментарии к Doc для Javadoc Tool:
@return (справочная страница)
Отключить @возврат для методов, возвращающих void и для конструкторов; включить его для всех других методов, даже если его содержимое полностью избыточным с описанием метода. Наличие явного тега @return позволяет кому-то быстро найти возвращаемое значение. Всякий раз, когда возможно, указать значения возврата для особых случаев (например, указать значение, возвращаемое при предоставлении аргумента вне пределов).
Если вы (как и я) действительно не любите нарушать DRY, то это одна из самых важных строк javadoc ref:
Возможно иметь комментарий только с разделом тега и без основного описания.
(@см. http://docs.oracle.com/javase/7/docs/technotes/tools/solaris/javadoc.html#tagsection)
Таким образом, совершенно справедливо (и работает) для простых методов для написания вашего javadoc:
/**
* @return the name of the object
*/
public String getName();
Итак, вы могли бы написать что-то вроде этого:
/**
* @return the n-th element of the object
*
* @param n index of element to get
*/
public String get( int n );
Что (после небольшого познания друг друга) более читабельны в источнике и лучше поддерживаются как более длинная форма, которая нарушает DRY.