每天早上七点三十，准时推送干货
一、简介
在开发项目的时候，我们可能时不时需要查阅官方 JDK API 文档javadoc注释规范，以便于更加清晰的了解某个类方法的用途以及正确的使用姿势，比如关于 HashMap 类的介绍。
打开 JDK 源码，你会看到代码上有大量的文档注释，包括包的描述、类的描述、方法描述以及类属性的描述说明等等，同时你还会惊奇的发现，源码上的注释与 JDK API 文档中的描述如出一辙，以 HashMap 为例，类注释描述如下！
实际上，JDK API 文档是根据 Javadoc 工具生成的！
那什么是 Javadoc 呢？
官方回答: Javadoc is a tool for generating API documentation in HTML format from doc comments in source code.
翻译过来的意思是：Javadoc 是一款能根据源代码中的文档注释来产生 HTML 格式的 API 文档的工具。
简单的说就是，只要你在 java 源码中按照标准的格式写注释，就可以利用 javadoc 这款工具自动生成配套的 java API 文档。
本篇文章的主要内容，就是总结 java 文档注释应该按照什么样的格式来写，只要格式对了，java API 文档就能按照工具来自动生成。
二、文档注释格式总结
Java 文档注释是专门为了用 javadoc 工具自动生成文档而编写的一套注释标准，通过 javadoc 命令可以把文档注释中的内容生成文档，并输出到 HTML 文件中，与一般的注释有所不同，相关的规则如下：
在类/方法上的文档标注一般分为三段，顺序如下：
说明：用于指明作者或者组织，可以附加邮箱或者超链接，如果有多少个作者就用多少个该标签。适用范围：包、 类、接口案例如下：
/**
* @author xxxx
* @author xxx@123.com
* @author xxxxx
*/
说明：用于指明最早出现在哪个版本，可填版本号或日期，有时也可表明可运行的JDK版本。适用范围：包、类、接口、方法、成员属性、构造器案例如下：
/**
* @since 1.4
* @since 15 April 2001
* @since JDK1.5
*/
说明：用于指明当前版本号。适用范围：包、 类、接口案例如下：
/**
* @version 1.8.3.4
*/
说明：用于将一些关键字或代码解析成代码样式。适用范围：包、类、接口、方法、成员属性、构造器案例如下：
/**
* xxxx,{@code int var = 1;}xxxx
*/
说明：对函数返回值的注释。适用范围：方法案例如下：
/**
* @return true 执行成功;false 执行失败.
*/
说明：用于方法的入参名及描述信息。适用范围：构造器、方法案例如下：
/**
* @param img the image to be drawn
*/
说明：只能用于对常量进行注释，该标签常用于写在字段上的 Javadoc 注释。适用范围：方法、成员属性案例如下：
/**
* Default start value. {@value #START_VALUE}
*/
说明：用户描述构造函数或方法所会抛出的异常。适用范围：方法、构造器案例如下：
/**
* @throws IllegalArgumentException
* if {@code fromIndex > toIndex}
*/
说明：用于创建一个超链接到相关代码。适用范围：包、类、接口、方法、成员属性、构造器注意事项：1、@link 和 @linkplain的区别在于：@link直接将将超链接中的地址当作显示的文本，其格式为 {@link 地址}；而 @linkplain可以自行设定显示的文本，其格式为{@link 地址 显示文本}，三个字段用空格隔开。2、@link 和 @see的区别在于：@link可以放在某一行中的任意位置；而 @see必须放在某一行中的最开始。
案例如下：
/**
* xxx {@link java.lang.String#charAt(int)}
* xxx {@link #sort(Object[])}
* xxx {@linkplain Comparable natural ordering}
* @see #deepHashCode(Object[])
*/
说明：用于继承父类的 javadoc 注释，父类的文档注释会被拷贝到子类。适用范围：方法案例如下：
/**
* {@inheritDoc}
*
* The speed of tiger will be returned.
*
* @return the speed of tiger
*/
说明：告诉用户该 API 已过时，并且已被哪些新的 API 取代了。用@see或 @link指向新的API。该旧的 API 之所以不删掉，通常是为了兼容性考虑。。适用范围：包、类、接口、方法、成员属性、构造器案例如下：
/**
* @deprecated As of JDK 1.1, replaced by
* {@link #setBounds(int, int, int, int)}
*/
说明：说明一个序列化属性。适用范围：方法、成员属性案例如下：
/**
* @serial description
*/
说明：用于说明通过 writeObject() 和 writeExternal() 方法写的数据。。适用范围：方法、成员属性案例如下：
/**
* @serialData description
*/
说明：用于说明一个 ObjectStreamField 组件。适用范围：方法、成员属性案例如下：
/**
* @serialField name type description
*/
最后，在使用文档注释时，通常会按照如下顺序进行使用。
三、java api 文档生成方式
Javadoc 是 Sun 公司提供的一个技术，它从程序源代码中抽取类、方法、成员等注释，然后形成一个和源代码配套的 API 帮助文档。
文档的创建命令如下：
javadoc -d 文档存放目录 -author -version 源文件名.java
这条命令编译一个名为源文件名.java的 java 源文件，并将生成的文档存放在文档存放目录指定的目录下，生成的文档中index.html就是文档的首页。
-author和-version两个选项可选项，使用者可以通过javadoc -help命令查看 javadoc 使用说明。
注意：Javadoc 默认只提取 public、protected 修饰的部分，如果要提取 private 修饰的部分，需要使用 -private。
下面是一个使用说明文档注释的简单实例。
/**
* 这个类演示了文档注释
*
* @author Ayan Amhed
* @version 1.2
*/
public class SquareNum {
/**
* This method returns the square of num.
* This is a multiline description. You can use
* as many lines as you like.
*
* @param num The value to be squared.
* @return num squared.
*/
public double square(double num) {
return num * num;
}
/**
* This method inputs a number from the user.
*
* @return The value input as a double.
* @throws IOException On input error.
* @see IOException
*/
public double getNumber() throws IOException {
InputStreamReader isr = new InputStreamReader(System.in);
BufferedReader inData = new BufferedReader(isr);
String str;
str = inData.readLine();
return (new Double(str)).doubleValue();
}
/**
* This method demonstrates square().
*
* @param args Unused.
* @return Nothing.
* @throws IOException On input error.
* @see IOException
*/
public static void main(String args[]) throws IOException {
SquareNum ob = new SquareNum();
double val;
System.out.println("Enter value to be squared: ");
val = ob.getNumber();
val = ob.square(val);
System.out.println("Squared value is " + val);
}
}
使用 javadoc 工具处理 SquareNum.java 文件，生成 javadoc api 文档，在命令行输入如下命令，即可实现文档的生成！
javadoc SquareNum.java
四、小结
Javadoc 是一款为程序生成 API 文档的工具，只需按照规定的格式编写代码文档注释，即可生成 API 的帮助文档。
本文主要围绕 java 文档标签的使用进行介绍，如果有错误的地方javadoc注释规范，欢迎网友留言指出！
五、参考
1、javadoc 官方文档
2、博客园 – 小白都看得懂的Javadoc使用教程
3、菜鸟教程 – Java 文档注释
admin
