Effective Java 学习笔记 如何为方法编写文档
目录
方法的文档注解设计的原则
Javadoc常用的文档注释
一些注意细节
通过Javadoc命令生成h5页面
这是第8章Java方法的最后一部分，聚焦为导出的API编写文档注释。
如果要想使得API真正可用，配套的文档是必须的。Java提供了Javadoc这个文档生成工具，极大的减轻了开发人员写文档的工作量。Javadoc可用利用对应的文档注释，根据源代码自动生成API文档（一个H5页面）。
方法的文档注解设计的原则
方法的文档注解应该能够简洁地描述出它和客户端之间的约定。除了专门为继承而设计的类中的方法，文档应该说明该方法做了什么，它应该列举出方法使用的所有前置条件（客户在调用这个方法之前需要满足的条件，这个条件一般需要通过@throws标签针对未受检异常进行表述）、后置条件（在调用完成后，哪些条件要满足）以及副作用（对于系统中其他部分的影响）。
Javadoc的注解一般声明在类、方法或者接口的开头之前，下面重新举一下第一篇文章里PositiveDivideTest的例子：
package test;public class PositiveDivideTest {public static void main(String[] args) {System.out.println(divide(10, 3));System.out.println(mode(10, 3));}/*** Returns a int whose value is divident divide divisor,* this method is used for positive number only* if {@literal dividend or divisor <=0}, throw ArithmeticException* @param dividend* @param divisor* @throws ArithmeticException if {@literal dividend or divisor <=0}* @return dividend divide divisor*/public static int divide(int dividend, int divisor){if(dividend<=0||divisor<=0){throw new ArithmeticException("dividend or divisor <=0");}return dividend / divisor;}/*** Returns a int whose value is dividend mod divisor* this method is used for positive number only* if {@literal dividend or divisor <=0}, throw ArithmeticException* @param dividend* @param divisor* @throws ArithmeticException if {@literal dividend or divisor <=0}* @return dividend mod divisor*/public static int mode(int dividend, int divisor){int quo = divide(dividend, divisor);return dividend - quo * divisor;}
}
注解由/** */进行声明（注意不要写成/* */），第一句话是概要描述，对于方法和构造器来说，概要描述应该是一个完整的动词短语，它描述了该方法所执行的动作。
Javadoc常用的文档注释
先介绍一下Javadoc有哪些常用的文档注释，Javadoc根据这些注释能够生成什么特定的文档解释。
| 注解 | 解释 | 标准写法 |
| @param | 注解方法的输入参数 | 一个名词短语，描述这个参数所表示的值 |
| @throws | 注解方法所抛出的异常 | 应该包含单词"if",紧接着一个名次短语，描述这个异常将在什么样的条件下抛出。 |
| @return | 注解方法的返回值 | 一个名词短语，描述这个返回值所表示的值 |
| @literal | 注解一些特殊字符（包含html元字符，如果不注释会报错） | 用{@literal}将相关字符包裹起来 |
| @code | 注解一段代码 | 用{@code}将相关代码包裹起来 |
| @implSpec | 在接口的方法注释中描述具体的实现细节，或者在父类方法中注解其自用模式下的语义 | 说明该方法的的目的以及默认实现细节，为继承类或者实现类使用者提供便利 |
一些注意细节
同一个类或者接口中的两个成员或者构造器，不应该具有相同的概要描述：尤其是重载的情况，要注意区分，至少要说明两者的区别在哪里。
尽量不要使用句点：因为句点加空格会提前终止描述，如果一定要使用请用{@literal}标签包裹起来。
当为泛型或者方法编写文档时，确保要在文档中说明所有的类型参数：
/****@param <K> the type of keys maintained by the map*@param <V> the type of mapped values*/枚举类型也一样，要对每一个常量做充足的说明。
为注解类型编写文档时，要确保在文档中说明所有成员：这个要求和方法一样。
静态方法的线程安全性需要在文档中进行说明。
通过Javadoc命令生成h5页面
在对方法进行注解后，可以通过Javadoc命令生成注解文档：
(base) MacBook-Pro:chapter8$ javadoc -d docs -sourcepath . -subpackages test-d docs指定输出目录为docs。-sourcepath .指定源代码路径为当前位置。-subpackages test为路径下要处理的包名。
在命令运行后会成功生成docs文件夹：
其中的index.html就是对应的文档页面：
