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

Example,

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

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

2. Refer current class or imported package’s other 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

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

 

Example

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

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

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.

rectangle_20150909

Expnation of Rectangle class, it contains the link of Square class.

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

square_setsize

Expnation of Square.setSize method, it contains the 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.

Reference

 

 

Sponsored Links

One response

Leave a Reply

Your email address will not be published.