CODEWITHSUNDEEP
javacoding-stylejavadoc
tunnuz
tunnuz

Reputation: 24028

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?

Upvotes: 56

Views: 42562

Answers (5)

David Kariuki
David Kariuki

Reputation: 1766

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


@apiNote, @implSpec, and @implNote


  1. API specification:

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

  1. API notes:

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

  1. 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.

  1. 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

  1. New Javadoc Tags @apiNote, @implSpec, and @implNote
  2. Oracle - How to Write Doc Comments for the Javadoc Tool

Upvotes: 4

fbahr
fbahr

Reputation: 883

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

Upvotes: 28

Naveen
Naveen

Reputation: 121

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

Upvotes: 11

janhink
janhink

Reputation: 5023

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
}

Upvotes: 60

Laurent Pireyn
Laurent Pireyn

Reputation: 6875

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

Upvotes: 6

Related Questions