java 文档注释格式为，以 /** 开始， 以 */ 结尾，示例
java 中有3种注释，
-
行注释, 从指定位置开始，当前代码行后面的内容是被注释内容
// 注释内容，表示从这里之后的内容在编译时会被丢弃
-
块注释：开始和结束标记之间的内容会被丢弃，可以跨越多行
-
文档注释: 与块注释区别在于开头是 /** ，并且，文档注释不能作用在方法内部
并且，文档注释会被编译成 html ，所以，通过某些关键字，可以实现超链接的功能，并且，可以通过 html 检查器来检查文档注释是否有语法错误
在 ide（eclipse idea 等）环境中，可以通过超链接跳转到其他的类，方法等，非常方便
在前面的条目中，我们曾分析过，为何要尽量使用接口交互以及用心设计方法名（6-3中）
但实际上，仅仅通过方法名就想完全说清楚方法的用途，方法的使用场景等是不可能的，这些只能做简要说明
想要实际描述清楚所有的情况，还需要使用文档注释
而这，就是文档注释的必要性，尤其是涉及与外部交互的时候
当你调用别人的类，方法，完善清晰的文档和模糊甚至没有的文档之间你的开发感受是非常容易对比出来的
同理，你的类和方法被别人调用的时候，如果没有完善的文档，别人的感受你也应该能理解，这在合作开发中极为重要
即便是自己写的，自己调用也必须书写完善的文档
大多数人都会有这种经历，发现一个方法交互写的很蠢，然后查记录（svn，git 或者本地历史，记录等）才发现，原来这是自己之前写的
文档注释的必要性不再赘述，说一下文档注释的一些要点
-
类，接口，构造器，方法和属性都应该添加文档注释，如果类可以序列化，应说明序列化形式（后面 75条）
-
方法注释应简洁地描述它和客户端之间的约定
除了专为继承而设计的类中的方法之外，这个约定应该说明这个方法做了什么，而不是说明他的工作细节
列举这个方法的所有前置条件和后置条件（调用之前和调用成功之后如果有必须的条件，应加以说明）
一般情况下，前置条件由 @throws 标签针对的未受检异常所隐含描述的
每个未受检的异常对应一个前提违例
如果有副作用（side effect），则应列出造成的副作用。
所谓副作用，是指系统状态中可观察到的变化，它不是为了获得后置条件而明确要求的变化。例如，方法中使用了多线程，启动了后台线程。例如，为了对集合去重，做了排序操作
描述类或方法的线程安全性
-
方法的每个参数都应对应一个 @param，描述对应的入参
-
如果方法有返回值（非 void），则要用 @return 描述
-
如果方法有抛出异常，则使用 @throws 标签描述
-
对于泛型，注解，枚举等因为本身比较简单，注释时要详细，不要遗漏属性，方法，变量等
另外，文档注释可以通过某些功能关键字或标签来实现特定功能
比如常用的 @see 可以写一个指向其他方法或类的链接，表示参考关系
javadoc 具有继承方法注释的特性，如果 api 元素没有文档注释，则javadoc会向上搜索超类的注释。这可以节省继承体系下的文档注释工作，但如果子类的覆盖有了某些超类不具有的特性，副作用等，最好将注释也补充完善。
注意：
虽然为所有导出的api 元素提供文档注释是必要的，但并非永远就够了。对于由多个相互关联的类组成的复杂 api ，通常有必要用一个外部文档来描述 api 的总体结构，对文档注释进行补充。如果有这样的文档，相关的类或包文档注释就应该包含一个对这个外部文档的链接