JavaDoc: where to add notes/remarks to documentation?

Question

When coding in C# I have always found the tag remarks very useful for providing notes about the implementation of a class or method, or to give information about the theory of what I was implementing. I am now using Java but I can't find an appropriate JavaDoc tag for this. Maybe in Java you accomplish this in a different manner, does anybody know?

Answer 1

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/).

Answer 2

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 }