Javadoc coding rule of @link, @linkplain, @see

How to write link reference in javadoc

See previous post for general javadoc explanation.

Basic rule

To show “label” which refers to other field class/method/member, where “label” is optional..

@see package.class#member label

Example,

/**
 *  Javadoc 
 *  @see SampleClass#methodName(int, int) methodName
 */

Here, package name is omitted. You can use omitted name to avoid writing long sentences.

Below is the list of how you can write links.

1. Refer current class member

@see  #field
@see  #method(Type, Type,...)
@see  #method(Type argname, Type argname,...)
@see  #constructor(Type, Type,...)
@see  #constructor(Type argname, Type argname,...)

When you refer current class member, it is possible to omit writing Package.class.

2. Refer current class or imported package’s other class 

@see  Class#field
@see  Class#method(Type, Type,...)
@see  Class#method(Type argname, Type argname,...)
@see  Class#constructor(Type, Type,...)
@see  Class#constructor(Type argname, Type argname,...)
@see  Class.NestedClass
@see  Class

When you refer member which is in current class or imported package’s class, it is possible to omit writing Package.

3. Refer other package’s member

@see  package.Class#field
@see  package.Class#method(Type, Type,...)
@see  package.Class#method(Type argname, Type argname,...)
@see  package.Class#constructor(Type, Type,...)
@see  package.Class#constructor(Type argname, Type argname,...)
@see  package.Class.NestedClass
@see  package.Class
@see  package

You must write explicitly (cannot omit) in this case.

Example

Write two classes, Rectangle class and Square class refer each other.

/**
 * Javadoc link test
 * It is super class of {@link Square}
 * @see Square
 */
public class Rectangle {

    private int width;
    private int height;

    /**
     * Sets size.
     * @param width  width of rectangle
     * @param height height of rectangle
     */
    public void setSize(int width, int height){
        this.width = width;
        this.height = height;
    }

    /**
     * Gets width
     * @return {@link #width}
     * @see #getHeight()
     */
    public int getWidth(){
        return width;
    }

    /**
     * Gets height
     * @return {@link Rectangle#height}
     * @see Rectangle#getWidth()
     */
    public int getHeight(){
        return height;
    }
}

The javadoc of getWidth method is using omitted link, and javadoc of getHeight method is writing link more specifically (which is not necessary usual). 

/**
 * Javadoc link test.
 * Square is subclass of {@link Rectangle}
 * @see Rectangle
 */
public class Square extends Rectangle {
    /**
     * Sets size.
     * Below two lines refers same method.
     * @param edge length of square
     * @see Rectangle#setSize
     * @see #setSize(int width, int height)
     */
    public void setSize(int edge) {
        super.setSize(edge, edge);
    }
}

Now the java documentation of these classes refers the other field properly. It can be also confirmed by IDE. For example, when you refer the class description of Rectangle class in Android studio, by pressing [Ctrl-q], it is refering Square class so that developer can easily jump.

In the same way, when we check Square.setSize method , it has a link of Rectangle.setSize method.

To get the link, I wrote in 2 way,

1. @see Rectangle#setSize
2. @see #setSize(int width, int height)

Now you can understand what kind of omitting is allowed or not. That is, it is ok as long as it is unique to identify which setSize method we are refering.

Appendix: Refer webpage (Linking to an external URL)  

[updated on 2015/10/23]

For the purpose of linking internet website, you can use HTML tag.

Example.

/**
 * @see <a href="https://corochann.com">corochannNote</a>
 */

Reference

• @seeタグ (参照リンク)
• Linking to an external URL in Javadoc?