【Java】浅谈JavaDoc文档注释

文档注释

我们知道，Java有三种注释：

• 单行注释：//
• 多行注释：/* */
• 文档注释：/** */

这里，文档注释是我们探讨的主角。

文档注释可以在程序中嵌入关于程序的信息。我们可以利用JDK提供的javadoc实用程序提取这些信息，并放到HTML文件中。

文档注释使得程序的文档化变得简单，是Java的重要内容。 感兴趣的看一下Java11的API文档吧。

比如java.util.Scanner的网页版官档内容如下：

而我们借助Eclipse IDE查看一下JDK源码：

上面的两个图是Scanner类的部分文档注释截图，可见文档注释里不仅仅有大量的英文注释用于解释，更是有许多@（javadoc标记），还有（HTML文档），内容十分丰富。

当然，其他类也是类似的，因为整个Java API库就是通过这种方式文档化的。

另说：JDK9+开始JavaDoc开始支持模块（Java模块的概念从JDK9正式引入Java体系）

JavaDoc标记 标签含义@author标识作者{@code}以代码字体原样显示信息，但不转换成HTML样式@deprecated指定程序元素已经过时{@docRoot}指定当前文档的根目录路径@exception标识某个方法或者构造函数抛出的异常@hidden禁止某元素显示在文档中{@index}给索引指定术语{@inheritDoc}直接从父类中继承文档注释{@link}插入指向另一个主题的内部链接{@linkplain}插入指向另一个主题的内部链接，但以纯文本字体显示链接{@literal}原样式显示信息，但不转换成HTML样式@param文档化形参@provides文档化模块提供的服务@return文档化方法的返回值@see指定对另一个主题的链接@serial文档化默认的可序列化域@serialData文档化writeObject()或writeExternal()方法写入的数据@serialField文档化ObjectStreamField组件@since声明引入特定更改的版本号{@summary}文档化某项的摘要(JDK10+)@throws相当于@exception@uses文档化模块所需要的服务(JDK9+){@value}显示一个常量的值，该常量必须是静态域@version指定程序元素的版本 文档注释示例

/**
 * This class test class Demo
 * @author BlankSpace
 * @version 4.1
 */
public class Test {
    //balabala
}

然后，看一下Scanner类类名上面的完整文档注释（Java每个类都是一大坨这个）

/**
 * A simple text scanner which can parse primitive types and strings using
 * regular expressions.
 *
 * 
A {@code Scanner} breaks its input into tokens using a
 * delimiter pattern, which by default matches whitespace. The resulting
 * tokens may then be converted into values of different types using the
 * various {@code next} methods.
 *
 * 
For example, this code allows a user to read a number from
 * {@code System.in}:
 * 
{@code
 *     Scanner sc = new Scanner(System.in);
 *     int i = sc.nextInt();
 * }
 *
 * 
As another example, this code allows {@code long} types to be
 * assigned from entries in a file {@code myNumbers}:
 * 
{@code
 *      Scanner sc = new Scanner(new File("myNumbers"));
 *      while (sc.hasNextLong()) {
 *          long aLong = sc.nextLong();
 *      }
 * }
 *
 * 
The scanner can also use delimiters other than whitespace. This
 * example reads several items in from a string:
 * 
{@code
 *     String input = "1 fish 2 fish red fish blue fish";
 *     Scanner s = new Scanner(input).useDelimiter("\\s*fish\\s*");
 *     System.out.println(s.nextInt());
 *     System.out.println(s.nextInt());
 *     System.out.println(s.next());
 *     System.out.println(s.next());
 *     s.close();
 * }
 * 

 * prints the following output:
 * 
{@code
 *     1
 *     2
 *     red
 *     blue
 * }
 *
 * 
The same output can be generated with this code, which uses a regular
 * expression to parse all four tokens at once:
 * 
{@code
 *     String input = "1 fish 2 fish red fish blue fish";
 *     Scanner s = new Scanner(input);
 *     s.findInLine("(\\d+) fish (\\d+) fish (\\w+) fish (\\w+)");
 *     MatchResult result = s.match();
 *     for (int i=1; i