JavaDoc【注释】生成API（开发文档）详解

一、综述（类注释及方法注释）

1.1 简介

Javadoc 是 Java 自带的一种工具，其可以从程序源代码中抽取类、方法、成员等注释形成一个和源代码配套的API帮助文档。也就是说，只要在编写程序时以一套特定的标记【Tag】作注释，在程序编写完成后，通过Javadoc就可以同时形成程序的开发文档了。
Java中有三种注释方法：

• //被注释语句
• /*被注释语句*/
• /**被注释语句*/

其中第三种专为 JavaDoc 设计，可以被 JDK 内置的 Javadoc 工具支持和处理。
  Javadoc在命令行使用还是比较复杂的，在Eclipse、IntelliJ IDEA等IDE中却比较方便，在命令行使用的麻烦的原因是众多的参数。

但是IDE傻瓜型的操作在有些时候还完成不了想要的任务。这时候，就需要懂得一些参数命令的用法了。
  生成 Javadoc 不要求你的Java代码是可编译的，唯一要求的是存在.java文件。

官方提供API帮助文档：

• JDK7：javadoc - The Java API Documentation Generator
• JDK8：javadoc

1.2 生成细节

注释文档的格式：

• 注释文档将用来生成HTML格式的代码报告，所以注释文档必须书写在类、域、构造函数、方法、定义之前。
• 注释文档由两部分组成：描述 和 标记。
• 以@开头的是标记。

Javadoc 生成的文档是 HTML 格式，而这些 HTML 格式化的标识符并不是 javadoc 加的，而是我们在写注释的时候写上去的。比如，需要换行时，不是敲入一个回车符，而是写入
，如果要分段，就应该在段前写入

。因此，格式化文档需要在文档注释中添加相应的 HTML 标识。文档注释的正文并不是直接复制到输出文件 (文档的 HTML 文件)，而是读取每一行后，删掉前导的 * 号及 * 号以前的空格，再输出到文档的。

注意：文档注释只说明紧接其后的类、属性或者方法。

描述

方法的简单注释：

注意细节：

1. 方法的简单注释，是注释第一行最后一个点号“.”之前的，之后的将在下面详细的叙述部分出现。
2. 如果方法简述的第一行最后没有点号（哪怕中间有点好），解析的时候会自动查找到下面行中最近的行末尾最后出现的点号。
3. IDE相当智能了，但是在格式化代码的时候原本的换行可能会被打乱，因此简单注释的第一行末尾的点号“.”之后使用
   进行换行。

详细细节：除了简单叙述外，其它部分的叙述也会出现在下面的详细叙述部分，也就是上面超链接的部分。

标记

标记以@开头：

Tag【标记】	描述	引入版本
@author	标明开发该模块的作者	1.0
{@code}	标明内部是代码示例	1.5
{@docRoot}	代表生成文档的根目录	1.3
@deprecated	标明方法或类已过时	1.0
@exception	对方法可能抛出的异常进行说明【@throws取代】	1.0
{@inheritDoc}	继承的时候把父类的注释都copy	1.4
{@link}	内联链接【代码字体格式】	1.2
{@linkplain}	内联链接【纯文本字体格式】	1.4
{@literal}	显示文本【与<pre>标签类同】	1.5
@param	对方法参数的说明	1.0
@return	对方法返回值的说明	1.0
@see	参考转向，也就是相关主题	1.0
@serial		1.2
@serialData		1.2
@serialField		1.2
@since	引入的版本	1.1
@throws	对方法可能抛出的异常进行说明	1.2
{@value}	值引用	1.4
@version	标明该类模块的版本	1.0

标记的顺序（Order of Tags）

1. @author (classes and interfaces only, required)
2. @version (classes and interfaces only, required. See footnote 1)
3. @param (methods and constructors only)
4. @return (methods only)
5. @exception (@throws is a synonym added in Javadoc 1.2)
6. @see
7. @since
8. @serial (or @serialField or @serialData)
9. @deprecated (see How and When To Deprecate APIs)

可以多次使用标记（Ordering Multiple Tags）

1. @author 标记应按时间顺序排列，并用逗号分隔。
2. @ param 标记应该在参数声明的顺序列出，这使它更容易在视觉上与声明相匹配的列表。
3. @throws 标记 (类同 @exception)应按字母顺序列出的例外的名字。
4. @see 标记遵循由近到远，参数由少到多，由上到下的顺序。

@see #field@see #Constructor(Type, Type...)@see #Constructor(Type id, Type id...)@see #method(Type, Type,...)@see #method(Type id, Type, id...)@see Class@see Class#field@see Class#Constructor(Type, Type...)@see Class#Constructor(Type id, Type id)@see Class