Как задокументировать побочные эффекты Java

Question

Существуют ли стандартные или лучшие практики для написания javadoc для методов языка Java/JVM, которые содержат побочные эффекты?

У меня есть определенный метод void, который изменяет один из параметров метода, но я не знаю, как документировать фактическое возвращаемое значение (поскольку нет фактического возврата).

/**
  * @param obj - reference object
  * @return obj - obj.name is changed to 'hello' //TODO figure out javadoc annotation
 */
void methodName(Object obj) {
   if (obj != null) {
       obj.name = "hello";
   }
}

Просто кажется, что нет хорошего способа пометить побочные эффекты на объекте, так как аннотации @param и @return на самом деле не определяют, что происходит.

Answer 1

Не существует стандартной аннотации Javadoc для описания побочных эффектов. Побочные эффекты обычно упоминаются в удобочитаемом описании метода. В вашем случае объект, который передается как параметр, изменяется, поэтому вы можете кратко повторить побочный эффект после @param тег.

В любом случае, @return тег не является правильным местом для документирования побочных эффектов: ваш метод имеет void как тип возвращаемого значения, поэтому он ничего не возвращает.

В вашем случае ваш Javadoc может выглядеть так:

/**
 * Methods a name. This method sets the "name" attribute of obj to "hello".
 * @param obj reference object ("name" attribute is modified by this method)
 */
void methodName(Object obj) {
   if (obj != null) {
       obj.name = "hello";
   }
}