1. Overview

1.概述

Javadoc is a great way of generating modern-day Java documentation in HTML format from the Java source code.

Javadoc是一种从Java源代码生成HTML格式的现代Java文档的好方法。

In this tutorial, we’ll focus on the @see and @link tags in doc comments.

在本教程中，我们将重点讨论文档注释中的@see和@link标签。

2. @see

2.@see

The format of the @see tag is quite simple:

@see标签的格式非常简单。

@see reference

For example, we can use it to mark an external link to the official Java documentation:

例如，我们可以用它来标记一个指向官方Java文档的外部链接。

/**
 * @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.

简而言之，当我们想要一个指向参考文献的链接或文本条目时，我们使用@see标签。这个标签为参考文献添加一个 “参见 “标题。一个文档注释可以包含任意数量的@see标签，所有这些标签都可以被归入同一个标题下。Oracle doc给了我们一些关于如何使用它的详细说明。这个标签是有效的，可以在任何文档注释中使用，包括包、概述、构造函数、类和接口。@see标签有三种变化，下面将讨论。

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 cases by looking out for a double quote (“) as a first character. Let’s consider an example:

这将为一个文本字符串添加一个文本条目，而不产生任何类型的链接。该字符串可以指向一个书页或任何其他需要提供的额外信息，以便进一步了解情况。Javadoc工具通过寻找作为第一个字符的双引号（”），将文本字符串与其他情况区别开来。让我们考虑一个例子。

/**
 * @see "This method performs some function."
 */
public void someMethod() {
  // do Something...
}

This will render as:

这将呈现为。

2.2. @see <a href=”URL”>label</a>

2.2.@see <a href=”URL”>标签</a>

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:

这将添加一个定义URL的链接。URL可以是一个相对的或绝对的URL值。Javadoc工具通过查看作为第一个字符的小于符号（<）来区别文本字符串和其他情况，然后添加一个定义URL#value的链接。URL#value是一个相对或绝对的URL。Javadoc工具通过寻找一个小于符号（<）作为第一个字符来区分这种情况和其他情况。考虑一下下面的例子，在一个锚标签中显示一个链接。

/**
 * @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

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:

这增加了一个定义了一个函数的链接。标签是可选的，当未定义时使用类中的原始成员名。-no限定符选项将包名从可见文本中移除。package.class#member指的是包、类、接口或字段名等元素名称。考虑下面的例子。

/**
 * @see String#toLowerCase() convertToLowerCase
 */
public void addingSeeToAMethod() {
  // do Something...
}

The standard HTML produced for the above annotation will look something like this:

为上述注释产生的标准HTML看起来会是这样的。

<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

3.@link

This is an inline tag. The format of the @link tag is pretty straightforward:

这是一个内联标签。@link标签的格式是非常直接的。

{@link  package.class#member  label}

Let’s look at the below example for using the @link tag:

让我们看一下下面这个使用@link标签的例子。

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

这将插入一个带有可见文本标签的内联链接。文本标签指向指定包、类或成员名称的文档。这个标签可以在任何地方使用，包括概览、包、类、方法、字段等。也可以在@return、@param和@deprecated等标签的文本部分内使用。这个标签与@see非常相似，因为两者都需要相同的引用，并且接受相同的package.class#member和标签语法。

The standard HTML produced for the above annotation will look something like this:

为上述注释产生的标准HTML看起来会是这样的。

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

4.@see和@link之间的相似之处

In this section, let’s look at the similarities between the @see and @link tags.

在本节中，让我们看看@see和@link标签之间的相似之处。

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:

我们可以在一个类、包或方法中多次使用@see和@link标签。 @see标签声明指向外部链接、类或方法的引用。@link标签也可以多次用于声明内联链接，或者与其他块状标签对比使用。请看下面的例子，显示了@see和@link标签的语法。

/**
 * 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

5.@see和@link之间的区别

In this section, let’s look at the difference between the @see and @link tags.

在本节中，让我们看看@see和@link标签之间的区别。

5.1. Both Belong to Different Tags

5.1.两者都属于不同的标签

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.

一个块状标签有一个@tag的形式，出现在一行的开头。它忽略了前面的星号、空白和分隔符（/**）。@see就是这样一个块状标签的例子。

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:

内联标签出现在大括号内，其形式为{@tag}。而且它应该被允许，并在任何允许文本的地方被解释。我们也可以用内联标签使用其他标签。它可以存在于描述或评论的任何地方。

/**
 * Some description here.
 *
 * @see java.lang.Object
 * @return  This will return {@link #toString() string} response.
 */

5.2. Displaying @see and @link Tag5.2.显示@see和@link标签

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:

@see和@link标签之间的主要区别是，一个标签生成一个行内链接，而另一个则在 “See Also “部分显示链接。而且，@link标签以大括号开始和结束，将其与其他行内文本分开。由于@see标签是一个块状标签，我们将明确创建它。

Consider the following example displaying the output for @see and @link tag:

考虑以下例子，显示@see和@link标签的输出。

/**
 *
 * 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:

这将在Javadoc中产生以下输出。

5.3. Using @see and @link Tag

5.3.使用@see和@link标签

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:

一个块状标签是独立使用的，不能被其他标签使用。另一方面，内联标签是用于文档注释内或作为一个内联链接。我们也可以将@link标签与其他块状标签一起使用。考虑下面的例子，我们将@link标签与一些其他块状标签一起使用。

/**
 * 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. Conclusion

6.结语

In this tutorial, we talked about using @see and @link tags correctly. Then we described the types of comment tags and different ways of using @see them. Finally, we also described 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 a text that points to a reference, and the @link tag describes a link in the text or some other tag as inline.

在本教程中，我们谈到了正确使用@see和@link标签。然后，我们描述了评论标签的类型和使用@see的不同方法。最后，我们还描述了@see和@link标签之间的一些主要区别。简而言之，我们可以使用@see标签来显示一个链接或一个指向参考的文本，而@link标签则将文本中的链接或其他一些标签描述为内联。