...
In general, you want to avoid things like this, where the doc doesn’t really do anything but explain what’s obvious and already contained in the class name:
Code Block |
---|
/** |
...
* Implementation of OurInterface. |
...
*/ |
...
public class OurInterfaceImplementation implements OurInterface { ... } |
Get/Set methods are often good examples of documenting the obvious:
Code Block |
---|
/** |
...
* @return Returns the xyz. |
...
*/ |
...
public String getXyz() { |
...
return xyz; |
...
} |
...
/** |
...
* @param xyz |
...
The xyz to set. |
...
*/ |
...
public void setXyz(String xyz) { |
...
this.xyz = xyz; |
...
} |
The idea is to provide useful information, or at least to not waste the reader’s time with useless information.
...