JavaDoc: where to add notes/remarks to documentation?

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?


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:

If you think implementation details are interesting enough to be a part of the Javadoc, you should simply provide them in a paragraph in the Javadoc comment itself:

 * Does something.
 * <p>
 * <b>Implementation details:</b><br />
 * Blah blah blah...
 * </p>
public void doSomething() {
    // ...

You can create your own custom tags too.

Here is a javadoc comment that includes the custom tag "@note":

     * Quark represents a quark.
     * @note If you spin a quark, it will spin forever!
    public class Quark {


To generate javadocs for the above, run javadoc like this:

javadoc -tag note:a:"Note:"


Need Your Help

What is the meaning of "... ..." token? i.e. double ellipsis operator on parameter pack

c++ c++11 variadic-templates

While browsing through gcc's current implementation of new C++11 headers, I stumbled upon "......" token. You can check, that the following code compiles fine [via].

What is the opposite of GROUP_CONCAT in MySQL?

mysql csv format pivot group-concat

I seem to come against this problem a lot, where I have data that's formatted like this: