JavaDoc: where to add notes/remarks to documentation?
As far as I know, there isn't any dedicated Javadoc tag for notes or remarks. Generally, the first sentence of Javadoc should give a brief description of the class/method/field. Then the full description should follow. And if you want to include any notes, a specialized paragraph with a "Note:" prepended should suffice.
/**
* Brief description. Full description of the method, generally without
* implementation details.
* <p>
* Note: Additional information, e.g. your implementation notes or remarks.
* </p>
* @param input description of the parameter
* @return description of return value
*
* @since version
* @author name of the author
*/
public boolean doSomething(String input)
{
// your code
}
With iteration 8 of the Java programming language, developers finally have been provided with three additional tags they can use in their code's documentation – and which should meet your needs: @apiNote
, @implSpec
and @implNote
(cf., for instance, for a more detailed discussion: blog.codefx.org/java/new-javadoc-tags/).