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就是对应的文档页面：