1. Overview
Javadoc is a great way of generating modern-day Java documentation in HTML format from the Java source code.
In this tutorial, we’ll focus on the @see, @link, and @inheritDoc tags in Javadoc comments.
2. @see
The format of the @see tag is quite simple:
@see reference
For example, we can use it to mark an external link to the official Java documentation:
/**
* @see <a href="https://docs.oracle.com/en/java/">Java Dcoumentation</a>
*/
In short, we use the @see tag when we want a link or a text entry that points to a reference. This tag adds a “See Also” heading to the reference. A document comment can hold any number of @see tags, all of which can be grouped under the same heading. The Oracle doc gives us some detailed instructions on how to use it. This tag is valid and can be used in any doc comment, including package, overview, constructor, class, and interface. The @see tag has three variations that are discussed below.
2.1. @see “text-string”
This adds a text entry for a text string without generating any type of link. The string can refer to a book page or any other additional information that needs to be provided for any further context. The Javadoc tool differs the text string from any other case by looking out for a double quote (“) as a first character. Let’s consider an example:
/**
* @see "This method performs some function."
*/
public void someMethod() {
// do Something...
}
This will render as:
2.2. @see <a*** ***href=”URL”>label
This adds a link that defines a URL. The URL can be a relative or an absolute URL value. The Javadoc tool differs the text string from any other case by looking at a less-than symbol (<) as the first character and then adds a link that defines the URL#value. The URL#value is a relative or absolute URL. The Javadoc tool distinguishes this from other cases by looking for a less-than symbol (<) as the first character. Consider the following example that displays a link within an anchor tag:
/**
* @see <a href="http://www.baeldung.com">Baeldung</a>
*/
public void someMethodV2() {
// do Something...
}
This will generate text as:
2.3. @see package.class#member label
This adds a link that defines a function. The label is optional and uses the original member name from the class when undefined. The -no qualifier option removes the package name from the visible text. The package.class#member refers to an element name like a package, class, interface, or field name. Consider the following example:
/**
* @see String#toLowerCase() convertToLowerCase
*/
public void addingSeeToAMethod() {
// do Something...
}
The standard HTML produced for the above annotation will look something like this:
<dl>
<dt><b>See Also:</b>
<dd><a href="../../java/lang/String#toLowerCase()"><code>convertToLowerCase<code></a>
</dl>
This will convert to the below output in the browser:
Note: We can use multiple spaces inside a label.
3. @link
This is an inline tag. The format of the @link tag is pretty straightforward:
{@link package.class#member label}
Let’s look at the below example for using the @link tag:
/**
* Use the {@link String#equalsIgnoreCase(String) equalsMethod} to check if two strings are equal.
*/
This inserts an inline link with a visible text label. The text label points to the documentation for the specified package, class, or member name. This tag can be used everywhere, including an overview, package, class, method, field, etc. This can also be used inside the text portion of tags like @return, @param, and @deprecated. This tag is very similar to @see since both require the same references and accept the same syntax for package.class#member and label.
The standard HTML produced for the above annotation will look something like this:
Use the <code>equalsMethod</code> to check if two strings are equal.
This will render as below in the browser:
4. Similarities Between @see and @link
In this section, let’s look at the similarities between the @see and @link tags.
We can use the @see and @link tag multiple times in a class, package, or method. The @see tag declares references that point to an external link, class, or method. The @link tag can also be used multiple times for declaring inline links or in contrast with other block tags. Consider the below example showing the syntax for @see and @link tag:
/**
* Use {@link String#toLowerCase()} for conversion to lower case alphabets.
* @deprecated As of Java 1.8 {@link java.security.Certificate} is deprecated.
* @return {@link String} object
* @see <a href="http://www.baeldung.com">Baeldung</a>
* @see String#hashCode() hashCode
*/
public String someMethod() {
// perform some function
return "";
}
5. Differences Between @see and @link
In this section, let’s look at the difference between the @see and @link tags.
5.1. Both Belong to Different Tags
We can categorize doc comments into two types:
- Block tags
- Inline tags
A block tag has a @tag form that appears at the beginning of a line. It ignores the leading asterisks, white space, and the separator(/**). @see is one such example of a block tag.
An inline tag appears within braces and has a form of {@tag}. And it should be allowed and interpreted anywhere that text is allowed. We can use other tags also with inline tags. It can exist anywhere in descriptions or comments:
/**
* Some description here.
*
* @see java.lang.Object
* @return This will return {@link #toString() string} response.
*/
The main difference between the @see and @link tags is that one generates an in-line link, whereas the other displays the link in the “See Also” section. Also, the @link tag begins and ends with curly braces that separate it from the rest of the in-line text. Since the @see tag is a block tag, we will create it explicitly:
Consider the following example displaying the output for @see and @link tag:
/**
*
* Use {@link String#toLowerCase()} for conversion to lower case alphabets.
* @deprecated As of Java 1.8 {@link java.security.Certificate} is deprecated.
* @return {@link String} object
* @see <a href="http://www.baeldung.com">Baeldung</a>
* @see String#hashCode() hashCode
*/
public String someMethod() {
// perform some function
return "";
}
This will generate the following output in the Javadoc:
5.3. Using @see and @link Tag
A block tag is used independently and cannot be used with other tags. On the other hand, an inline tag is used inside a doc comment or as an inline link. We can use the @link tag with other block tags also. Consider the following example where we are using the @link tag with some other block tag:
/**
* Some description here.
*
* @see java.lang.Object
* This is a {@link #getClass() } method.
* @see #getClass() Use {@link #toString()} for String conversion.
* @deprecated As of JDK 1.1, replaced by {@link #someMethod()}
*/
6. @inheritDoc
Unlike the @see tag, @inheritDoc is an inline tag:
{@inheritDoc}
This tag adopts the concept of inheritance in object-oriented programming. It inherits the documentation of a similar element in a super-class or interface. This means we don’t need to repeat common documentation.
The tag is valid in the main description block of a method and the text arguments of @return, @throws, and @param of method tags.
6.1. Usage
@inheritDoc can only inherit from a locally available super-class or interface. To try it out, let’s create a new interface similar to Runnable:
public interface MyRunnable {
/**
* Runs this operation.
*/
void run();
}
The interface has a simple description of the run() method.
Let’s implement the interface by creating a new class,TimeOuttputterRunnable:
public class TimeOutputterRunnable implements MyRunnable{
/**
* {@inheritDoc}
* Outputs current time in epoch milliseconds when run.
*/
public void run(){
System.out.println(System.currentTimeMillis());
}
}
The class implements the only method from the interface. It uses @inheritDoc to inject the documentation from the interface. We’ve also added some additional text specific to this implementation. We can see both the parent interface’s documentation and the text from this class in the resulting Javadoc:
7. Conclusion
In this tutorial, we talked about using @see, @link, and @inheritDoc tags. Then we described the types of comment tags and different ways of using @see in them.
We also saw some of the major differences between the @see and the @link tag. In short, we can use the @see tag for displaying a link or text that points to a reference. The @link tag describes a link in the text or some other tag as inline.
Finally, we imported Javadoc from an interface using @inheritDoc. Its function made it different from @see and @link. The @see and @link functions are to put cross-references into Javadoc*. The @inheritDoc*is for importing Javadoc from a superclass or interface.