Documenting Java Code

Introduction

Documentation for java code is often generated using javadoc. Javadoc was created by Sun Microsystems for the purpose of generating API documentation in HTML format from java source code. Using the HTML format gives the convenience of being able to hyperlink related documents together.

Syntax

/** – start of JavaDoc on a class, field, method, or package
@author // To name the author of the class, interface or enum. It is required.
@version // The version of that class, interface or enum. It is required. You could use macros like %I% or %G% for you source control software to fill in on checkout.
@param // To show the arguments (parameters) of a method or a constructor. Specify one @param tag for each parameter.
@return // To show the return types for non-void methods.
@exception // Shows what exceptions could be thrown from the method or constructor. Exceptions that MUST be caught should be listed here. If you want, you can also include those that do not need to be caught, like ArrayIndexOutOfBoundsException. Specify one @exception for each exception that can be thrown.
@throws // Same as @exception.
@see // Links to a method, field, class or package. Use in the form of package.Class#something.
@since // When this method, field or class was added. For example, JDK-8 for a class like java.util.Optional<T>.
@serial, @serialField, @serialData // Used to show the serialVersionUID.
@deprecated // To mark a class, method or field as deprecated. For example, one would be java.io.StringBufferInputStream. See a full list of existing deprecated classes here.
{@link} // Similar to @see, but can be used with custom text: {@link #setDefaultCloseOperation(int closeOperation) see JFrame#setDefaultCloseOperation for more info}.
{@linkplain} // Similar to {@link}, but without the code font.
{@code} // For literal code, such as HTML tags. For example: {@code <html></html>}. However, this will use a monospaced font. To get the same result without the monospace font, use {@literal}.
{@literal} // Same as {@code}, but without the monospaced font.
{@value} // Shows the value of a static field: The value of JFrame#EXIT_ON_CLOSE is {@value}. Or, you could link to a certain field: Uses the app name {@value AppConstants#APP_NAME}.
{@docRoot} // The root folder of the JavaDoc HTML relative to the current file. Example: <a href=”{@docRoot}/credits.html”>Credits</a>.
HTML is allowed: <code>“Hi cookies”.substring(3)</code>.
*/ – end of JavaDoc declaration

Remarks

Javadoc is a tool included with the JDK that allows in-code comments to be converted to an HTML documentation. The Java API Specification was generated using Javadoc. The same is true for much of the documentation of 3rd-party libraries.

Found a mistake? Have a question or improvement idea? Let me know.

Table Of Contents