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?

janhink · Accepted Answer · 2013-06-26T07:36:04.983

55

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
}

edited Jun 26 '13 at 07:36

answered Apr 11 '11 at 10:04

janhink

4,943
3
29
37

Generally if you open (xml-)tags you should close them somewhere. – AlexS Feb 20 '12 at 10:46
2

[This answer](http://stackoverflow.com/a/34424961/2525313) should now be considered correct. – Nicolai Parlog Feb 09 '16 at 21:55

score 26 · Answer 2 · answered Dec 22 '15 at 21:46

26

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

answered Dec 22 '15 at 21:46

fbahr

853
1
8
13

2

It would be nice to explain use-cases of those tags directly in your answer (what are the differences between them). – Genhis Jun 18 '19 at 08:39

score 8 · Answer 3 · answered Aug 25 '15 at 21:53

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:" Quark.java

Source: http://www.developer.com/java/other/article.php/3085991/Javadoc-Programming.htm

score 6 · Answer 4 · answered Apr 11 '11 at 09:57

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() {
    // ...
}

score 2 · Answer 5 · answered Jul 27 '22 at 06:50

You can use @apiNote, @implSpec, and @implNote

@apiNote, @implSpec, and @implNote

API specification:

This is a description that applies equally to all valid implementations of the method, including preconditions, postconditions, etc.

API notes:

These are commentary, rationale, or examples pertaining to the API.

Implementation specification:

This is where we say what it means to be a valid default implementation (or an overridable implementation in a class), such as throws UOE. Similarly this is where we'd describe what the default for putIfAbsent does. It is from this box that the would-be-implementer gets enough information to make a sensible decision as to whether or not to override.

Implementation notes.

Informative notes about the implementation, such as performance characteristics that are specific to the implementation in this class in this JDK in this version, and might change. These things are allowed to vary across platforms, vendors and versions.

The proposal: add three new Javadoc tags, @apiNote, @implSpec, and @implNote. (The remaining box, API Spec, needs no new tag, since that's how Javadoc is used already.) @impl{spec,note} can apply equally well to a concrete method in a class or a default method in an interface.

So the new Javadoc tags are meant to categorize the information given in a comment. It distinguishes between the specification of the method's, class's, behavior (which is relevant for all users of the API - this is the "regular" comment and would be @apiSpec if it existed) and other, more ephemeral or less universally useful documentation. More concretely, an API user can not rely on anything written in @implSpec or @implNote, because these tags are concerned with this implementation of the method, saying nothing about overriding implementations.

For more information, check the references below

JavaDoc: where to add notes/remarks to documentation?

5 Answers5

@apiNote, @implSpec, and @implNote

Linked