Java Doc -- `{@link}` 和 `@see` 的用法

前言

Java Doc 是一种为 Java 代码生成文档的标准工具。它通过特殊的注释格式帮助开发者记录代码的功能、参数、返回值等信息，从而生成易于阅读的 HTML 文档。本文将详细介绍如何使用 {@link} 和 @see 标签来增强 Javadoc 的链接功能。

1. 什么是 {@link}？

{@link} 标签用于在 Javadoc 注释中创建指向其他文档元素（如类、方法、字段等）的链接。这个标签使得用户能够通过点击文档中的链接快速跳转到相关的类或方法的定义处。

使用方法

• {@link} 会在链接文本前后自动添加空格。
• @link 则不会添加空格。

示例

假设我们有一个方法 processList，它接受一个字符串列表作为参数，并返回一个新的字符串列表。

/**
 * 这个方法返回一个 {@link java.util.List} 实例，该实例包含一些 {@link java.lang.String} 对象。
 *
 * @param input 输入参数，类型为 @link java.util.List<java.lang.String> 的集合
 * @return List<String> 类型的结果
 */
public List<String> processList(List<String> input) {
    // 方法实现
}

在这个例子中，{@link java.util.List} 创建了一个指向 java.util.List 类的链接，而 @link java.util.List<java.lang.String> 则直接指明了类型参数。

2. 什么是 @see？

@see 标签用于提供对其他相关文档的引用。通常在类或方法级别的文档块中使用，用以指向其他相关的 API 或者概念性文档。

使用方法

@see 标签通常放在文档注释的底部，并且可以用于指向任何相关的类、方法或字段。

示例

考虑一个名为 DataSorter 的类，其中包含了两个排序方法：sort 和 reverseSort。

/**
 * 这个类实现了数据排序功能。
 *
 * @see java.util.Collections#sort(List)
 * @see #reverseSort()
 */
public class DataSorter {

    /**
     * 反向排序方法。
     *
     * @see #sort()
     */
    public void reverseSort() {
        // 反向排序的实现
    }

    /**
     * 正常排序方法。
     */
    public void sort() {
        // 正向排序的实现
    }
}

在这个例子中，@see 指向了 Collections.sort 方法以及类内部的另一个方法 reverseSort()。

注意事项

1. 正确性：确保你的类名或其他引用是正确的，否则生成的 Javadoc 可能无法正确解析这些链接。
2. 上下文：{@link} 只能在 Javadoc 注释内使用，并且需要编译器支持以生成正确的链接。
3. 嵌套使用：{@link} 可以嵌套使用，以便创建更复杂的链接结构。