Is there a standard or best practice for writing javadocs for Java/JVM language methods which contain side effects?
I have a void method defined, which modifies one of the method parameters, but do not know how to document the actual return value (since there is no actual return).
/**
* @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";
}
}
It just seems that there is no good way to tag the side effects on the object, since the @param and @return annotations do not really dictate what is going on.
There is no standard Javadoc annotation to describe side effects. Side effects are typically mentioned in the human-readable description of the method. In your case, the object which is passed as a parameter is modified, so you can consider briefly repeating the side effect after the @param
tag.
In any case, the @return
tag is not the correct place to document side effects: your method has void
as return type, so it does not return anything.
In your case, your Javadoc could look like:
/**
* 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";
}
}