第44条 为所有导出的API元素编写文档注释
如果要想使一个API真正可用，就必须为其编写文档。传统意义上的API文档是手动生成的，所以保持文档与代码同步是一件很繁琐的事情。Java环境提供了一种被称为Javadoc的实用工具，从而使这项任务变得很容易。Javadoc利用特格式的文档注释，根据源代码自动产生API文档。
如何使用Javadoc？相关资料：http://blog.csdn.net/nothing0318/article/details/7258523
1.在myeclipse中点击导航栏中的 project->Generate javadoc弹出如下界面，然后勾选需要生成文档的包以及生成文档的位置。
da74efb0892d41c9ad951d974391789b.png
如何添加中文javadoc？相关资料： http://www.cnblogs.com/mq0036/p/3788511.html
2.在dos命令提示符中输入：javadoc -d myhelp -author -version Register.java（也可以编译整个文件夹，javadoc -d myhelp -author -version test）
-d 表示生成的目录位置，myhelp表示生成文档所在当前目录下的文件夹名
-author是作者的名字 -version是版本号（这两项非必填项，不写的话不会生成相应的文档注释内容）
ps:如果注释中有中文，需要在dos命令中加入-encoding utf-8 -charset utf-8
基础知识：
1./**this is a description*/注释若干行，并写入 javadoc 文档
2.文档注释三部分：
/**
* show 方法的简述.
* <p>show 方法的详细说明第一行<br>
* show 方法的详细说明第二行
* @param b true 表示显示，false 表示隐藏
* @return 没有返回值
*/
public void show(boolean b) {
frame.show(b);
}
第一部分是简述。文档中，对于属性和方法都是先有一个列表，然后才在后面一个一个的详细的说明
第二部分是详细说明部分。该部分对属性或者方法进行详细的说明，在格式上没有什么特殊的要求，可以包含若干个点号。
第三部分是特殊说明部分。这部分包括版本说明、参数说明、返回值说明等。
- @param b true 表示显示，false 表示隐藏
- @return 没有返回值
添加文档注释规范：
一、为了正确地编写API文档，必须在每个被导出的类、接口、构造器、方法和域声明之前增加一个文档注释。
二、方法的文档注释应该简洁的描述出它和客户端之间的约定。这个约定应该说明这个方法做了什么，而不是说明它是如何完成这项工作的。文档注释应该列举如下内容：
1.前提条件（precondition） 前提条件是指为了使客户能够调用这个方法，而必须满足的条件；
2.后置条件（postcondition） 所谓后置条件是指在调用成功完成之后，哪些条件必须要满足；
3.副作用（side effect） 副作用是指系统状态中可以观察到的变化，它不是为了获得后置条件而明确要求的变化；
4.类或者方法的线程安全性（thread safety）（详见70条） 当一个类的实例或者静态方法被并发使用时，这个类行为的并发情况。
文档注释示例：
/**
* Returns the element at the specified position in this list.
*
* <p>This method is <i>not</i> guaranteed to run in constant
* time. In some implementations it may run in time proportional
* to the element position.
*
* @param index index of element to return; must be
* non-negative and less than the size of this list
* @return the element at the specified position in this list
* @throws IndexOutOfBoundsException if the index is out of range
* ({@code index < 0 || index >= this.size()})
*/
E get(int index);
•文档注释必须以/**开头，否则Javadoc无法识别。
•文档注释第一句话作为概要描述。概要描述必须独立地描述目标元素的功能，同一个类或接口中的任意两个成员或构造器，不应该具有相同的概要描述。即使是重载方法也不行。
•每个参数都应该有一个@param标签，标签后面第一个单词为参数名称，接着是对该参数的解释和要求。
•返回类型非void的方法都应该有一个@return标签，描述返回值所表示的内容。
•该方法可能抛出的每一个异常，无论是受检异常还是非受检异常，都要对应一个@throws标签。标签后面第一个单词为异常类型，接着是一句话，应该以if开头，描述该异常将在什么情况下被抛出。@param、@return和@throws都不以句点结束。
• @code标签可用于任何需要展示代码的地方，被该标签包围的内容会以特殊的字体显示，并且不对其中内容做任何HTML解析。
•按惯例，单词“this”用在实例方法的文档注释中时，应该始终是指方法调用所在的对象。
•可以用@literal标签展示包含HTML元字符的句子。它除了不改变显示样式外，其余效果和@code一样。
Java 1.5发行版本中增加的三个特性在文档注释中需要特别小心：泛型、枚举和注解。当为泛型或者方法编写文档时，确保要在文档中说明所有的类型参数。
/**
* @author zhaiyanming
* @version 1.0
* @param <K> the type of keys maintained by the map
* @param <V> the type of mapped values
*/
public interface Map<K, V> {
//dosomething
}
当为枚举类型编写文档时，要确保在文档中说明常量，以及类型，还有任何公有的方法。
/**
* three primary colours
* @author zhaiyanming
* @version 1.0
* return enum
*/
public enum Color {
/** Red, the color of blood. */
RED,
/** Green, the color of grass. */
GREEN,
/** Blue, the color of sea. */
BLUE;
}
为注解类型编写文档时，要确保在文档中说明所有成员，以及本身类型。对于该类型的概要描述，要使用一个动词短语，说明当程序元素具有这种类型的注解时它表示什么意思。
import java.lang.annotation.ElementType;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
* Indicates that the annotated method is a test method that
* must throw the designated exception to succeed.
* @author zhaiyanming
* @version 1.0
*/
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface ExceptionTest {
/**The exception that the annotated test method must throw
* in order to pass. (The test is permitted to throw any
* subtype of the type described by this class object.) */
Class<? extends Exception> value();
}
类的导出API有两个容易被人忽略的特征：
1.类是否是线程安全的应该在文档中对它的线程安全级别进行说明。（如70条所述）
2.如果类是可序列化的，就应该在文档中说明它的序列化形式。（如第75条所述）
简而言之，要为API编写文档，文档注释是最好、最有效的途径。对于所有可导出的API元素来说，使用文档注释应该被看作是强制性的。要采用一致的风格来遵循标准的约定。在文档注释内部出现任何HTML标签都是允许的，但是HTML字符必须要经过转义。
