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

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

1. 为了正确的编写API文档，必须在每个被导出的类、接口、构造器、方法和域声明之前增加一个文档注释
2. API文档应该体现以下几点：
   • 前提条件(参数需要满足的要求) @param、@throws
   • @return
3. 同一个类或接口中的两个成员或者构造器，不应该具有相同的概要描述
4. 如果代码中出现了泛型，确保要在文档中说明所有的类型参数
5. 为枚举类型编写文档时，要确保在文档中说明常量
6. 为注解编写文档时，要说明清除所有成员
7. 类或者静态方法是否线程安全，应该在文档中进行声明

思考

1. 这篇内容明显是为框架开发写的，我们作为框架的使用者其实没有必要做到这么详细
2. 对于日常的开发，如果一个方法逻辑相对比较复杂，我会在方法上加上注释，说明入参出参以及大概的逻辑