Checkstyle Ожидаемый тег @param для ошибки 'id'

Я использую checkstyle в своей кодовой базе, http://checkstyle.sourceforge.net/, и у меня есть вопрос по JAVADOC.

У меня есть статические функции, подобные этому:

 **
 * @param id
 */
public static void getName(final String id) {
 }

где checkstyle жалуется на

Ожидаемый тег @param для 'id'

Когда я даю описание, подобное

@param id id

тогда он работает нормально, но я не хочу давать описание для каждого параметра и возврата. Есть ли альтернатива исправить это?


java checkstyle
person user864077    schedule 24.02.2012    source источник

Ответы (3)


arrow_upward
15
arrow_downward

Вы правы - это предупреждение означает, что у вас нет описания параметра. Если вы не хотите описывать параметр, зачем упоминать его? Ваш текущий JavaDoc не имеет смысла и занимает только бесценное место в редакторе.

Либо полностью удалите параметр из JavaDoc (я думаю, его значение очевидно из контекста), либо задокументируйте его должным образом. И

/**
 * id The id
 */

не является надлежащей документацией.

person Tomasz Nurkiewicz    schedule 24.02.2012
comment
Я думаю, это имеет смысл. Но все же в моем коде само имя параметра говорит само за себя. Поэтому я должен скопировать и вставить имя параметра в качестве описания для всех вызовов моего метода, которые я считаю бесполезными. Я проверил документацию checkstyle, но не смог найти ничего, чтобы отключить это предупреждение описания. - person user864077; 24.02.2012
comment
@user864077 user864077 - Вы думаете, что теперь это говорит само за себя, но поверьте мне, это не так. Когда вы наймете младшего программиста, ему будет непонятно. Когда вы вернетесь к коду 5 лет спустя, он может быть вам не ясен. Десятилетия опыта подтверждают это. Смотрите мой ответ. - person Stephen P; 24.02.2012
comment
Я думаю, вы неправильно понимаете. Javadoc уже может понять сигнатуру функции getName даже без комментариев. Когда вы ставите @param id whatever, часть id указывает javadoc, для какого параметра вы хотите добавить описание. - person Darien; 24.02.2012

arrow_upward
3
arrow_downward

Зачем запускать checkstyle, если вы собираетесь его игнорировать?

Я во многом согласен с ответом @Tomasz Nurkiewicz, за исключением того, что я обязательно задокументирую его.

Значение final String id может быть очевидным. вам. На сейчас. Метод getName тоже может быть очевиден — пока.

Когда я смотрю на него, я понятия не имею, что он делает или какой «идентификатор» мне нужно передать. Получает ли он полное юридическое имя пользователя? Какое имя они ввели? Их [фамилия, имя] имя? Какую строку идентификатора мне нужно передать? Внутренний идентификационный номер/код приложения? У вас нет никакого javadoc для того, что делает сам метод.

/**
 * Gets the indicated user's full name as entered when they registered.
 * @param id The application internal id generated when the user registered.
 * @return "void" ???  How do you get a name if it returns VOID?
 */
public static void getName(final String id) {
    ...
}

Я бы объявил это как public static String getName(...), потому что как получить имя, если оно ничего не возвращает? Если он делает что-то еще, например помещает имя где-нибудь, вы можете получить его позже, тогда (1) это не должно называться «getName» и (2) вам определенно нужно задокументировать этот факт в вашем javadoc .

person Stephen P    schedule 24.02.2012
comment
Спасибо за информацию. Я только что создал пример метода getName(), чтобы проиллюстрировать свой вопрос. - person user864077; 24.02.2012

arrow_upward
1
arrow_downward

Вы можете исправить это, изменив свой комментарий

/**
* this is comment of function 
* @param id **this is id of table**
* @param username **this is name of user need for login**
*/

Пожалуйста, сосредоточьтесь на ** {текст} **, чтобы исправить эту ошибку. Спасибо

person Tien Nguyen    schedule 05.08.2015