EffectiveJava学习笔记24：为所有导出的API元素写文档注释

为所有导出的API元素写文档注释

实际上就是为API元素写javadoc注释。

 

文档注释规范

具体使用这里就不讲了，在java编程思想的笔记中已写过具体的一些使用了

这里记录下文档注释的规范：

1.方法的文档注释约定

   1.1 方法的文档注释应该在文档中描述方法的一些约定联系

   1.2 方法的文档注释应该让它的每个参数都有一个@param标签，来解释参数

   1.3 方法的文档注释应该有一个@return标签，说明返回值（返回为void的除外）

   1.4 方法的文档注释无论是受检的还是非受检的都要有一个@throws标签，用于说明异常抛出，在什么样的条件下抛出。

   1.5 方法的文档注释可概要描述该方法的功能动作。

2.为一些特殊形式编写文档注释的约定

    2.1 为泛型编写文档注释时，要在文档中说明所有的类型参数，比如：T、K、V ，还是用@param

    2.2 为枚举类型编写文档时，要确保文档中说明常量，就是在枚举中的每个常量上面写上一行说明，不需要使用标签（@）

    2.3 为注解类型编写文档时，要确保在文档中说明所有成员。就是自定义注解时，注解接口里面的所有成员（变量、方法等）

    2.4  对于类或者静态方法的线程安全，应该在文档中说明它的线程安全级别。