要想一个API真正可用，就必须为其编写文档。
Javadoc根据源代码中特殊格式的文档注释自动生成API文档。
jdk5引入的Javadoc标签：{@literal}和{@code}
为了正确地编写API文档，必须在每个被导出的类、接口、构造器、方法和域声明之前增加一个文档注释。
如果类是可序列化的，也应该对它的序列化形式编写文档。
方法的文档注释应该简洁地描述它和客户端之间的约定，这个约定应该说明这个方法做了什么，而不是说明它是如何完成这项工作的。
文档注释应该列举出这个方法的所有前置条件和后置条件
前置条件：为了使客户能够调用这个方法，而必须要满足的条件；
前置条件是由@throws标签针对未受检的异常所隐含描述的;每个未受检的异常都对应一个前提违例。
也可以在一些受影响的参数的@param标记中指定前置条件。
后置条件：在调用成功完成之后，那些条件必须要满足。
每个方法应该在文档中描述它的副作用
副作用：系统状态中可以观察到的变化，它不是为了获得后置条件而明确要求的变化。
文档注释应该描述类或者方法的线程安全性
方法文档注释
为了完整地描述方法的约定，方法的文档注释应该让每个参数都有一个@param标签，以及一个@return标签（除了这个方法的返回类型为void）,以及对于该方法抛出的每个异常，无论是受检的还是未受检的，都有一个@throws标签。
跟在@param标签或者@return标签后面的文字应该是一个名词短语，描述了这个参数或者返回值所表示的值。
跟在@throws标签之后的文字应该包含单词if，紧接着是一个名词短语，它描述了这个异常将在什么样的条件下会被抛出。有时候，也会用算术表达式来代替名词短语。
按惯例，@param、@return、@throws标签后面的短语或者子句不用句点来结束。
{@code}标签
使该代码片段以代码字体进行呈现，并限制HTML标记和嵌套的Javadoc标签在代码片段中进行处理。允许在代码片段中使用小于号(<)。在JDK5之前，必须使用HTML标签和HTML转义，将代码片段包含在文档注释中（没有必要使用HTML的<code>和<tt>标签）。
{@code}避免了转义HTML元字符。
将多个代码示例包含在一个文档注释中可以使用<pre>{@code}{@code}</pre>
{@literal}除了不以代码字体渲染文本，跟@{code}标签一样。
文档注释在源代码和产生的文档中都应该是易于阅读的。如果无法同时满足两者，则产生的文档的可读性要优于源代码的可读性。
每个文档注释的第一句话是概要描述。概要描述必须独立地描述目标元素的功能。
为了避免混淆，同一个类或者接口中的两个成员或者构造器不应该使用相同的概要描述。
注意概要描述中是否包含句点，句点会过早地终止这个概要描述(如果有句点可以使用{@literal})。
概要描述很少是个完整的句子。
对于方法和构造函数，概要描述应该是个完整的动词短语(包含任何对象)，它描述了该方法所执行的动作。
对于类、接口或域，概要描述应该是一个名词短语，它描述了该类或者接口的实例，或者域本身所代表的事物。
JDK5泛型、枚举 注解
当为泛型或者方法编写文档时，确保要在文档中说明所有的类型参数。
当为枚举类型编写文档时，要确保在文档中说明常量，以及类型，还有任何公开的方法。
为注解类型编写文档时，要确保在文档中说明所有成员，以及类型本身。
注释类型的概要描述要使用一个动词短语，说明当程序元素具有这种类型的注释时它表示什么意思。
包级私有的文档注释
包级私有的文档注释应该放在package-info.java文件中。package-info.java可以（非必须）包含包声明和包注解。
线程安全性
应该对类的线程安全级别进行说明。
如果类是可序列化的，应该对类的序列化形式进行说明。
继承方法注释
Javadoc具有“继承”方法注释的能力。如果API元素没有文档注释，Javadoc将会搜索最为适用的文档注释，接口的文档注释优于超类的文档注释。
{@inheritDoc}从超类中继承文档注释的部分内容。
类可以重用它所实现的接口的文档注释，而不需要拷贝这些注释。
HTML有效性检查器
降低文档注释出错的可能性。
复杂API
对于由多个相互关联的类组成的复杂API，有必要用一个外部文档来描述该API的总体结构，对文档注释进行补充，如果有这样的文档，相关的类或者包文档注释就应该包含一个对这个外部文档的链接。
总结
要为API编写文档，文档注释是最好、最有效的途径。
对于所有可导出的API元素来说，使用文档注释应该被看作是强制性的。
要采用一致的风格来遵循标准的约定。
在文档注释内部出现任何HTML标签都是允许的，但是HTML元字符必须要经过转义。
