Javadoc and the @see tag

Javadoc, as you know, is a tool for documenting your source code in the Java language. It consists of specially-formatted comments that describe the classes, methods, and fields of your Java program. IDEs leverage Javadoc comments to help inform developers of how various APIs function (for example, hovering your mouse over a method in Eclipse will display that method's Javadoc). You can also run the "javadoc" command, which comes packaged with the JDK, to generate an HTML webpage containing the Javadoc comments of your entire code base.

Javadoc syntax defines a collection of tags. Tags allow you to describe specific aspects of your code, such as the return value of a method or the author of class. One of these tags is @see, which is like a "see also" reference. In this blog post, I'm going to describe the three ways to use @see.

1) Referring to a class or method. One way to use @see is to refer the user to another class or method within your code base. An import statement for the class you want to reference must be added to the Java code. Then, simply put the class name after the tag.

import com.example.RefClass;
/*
 * Description of this class.
 * @see RefClass
 */
public class MyClass{}

To refer to a method, put a #, followed by the method name, after the class name. If the method is overloaded, then be sure to include the parameters as well (enclosed in parenthesis) to remove any ambiguity as to which method you are referring to. Javadoc gurus will recognize this as the same syntax that's used with the @link tag.

import com.example.RefClass;
/*
 * Description of this class.
 * @see RefClass#execute(String, int)
 */
public class MyClass{}

2) Referring to a website. Another way of using @see is to refer to a website. For this, you must use the HTML <a> tag.

/*
 * Description of this class.
 * @see <a href="http://example.com">Library website</a>
 */
public class MyClass{}

3) Plain text. You can also just put plain text within the @see tag. However, it must be surrounded with double quotes in order to prevent the Javadoc parser from treating it like a class name.

/*
 * Description of this class.
 * @see "Library Documentation"
 */
public class MyClass{}