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

  如果要想使一个API真正可用，就必须为其编写文档。传统意义上的API文档是手工生成的，所以保持文档与代码同步是一件很繁琐的事情。Java编程环境提供了一种被成为Javadoc的实用工具。Javadoc使用特殊格式的文档注释（documentation comments）（通常称为doc注释（doc comments））从源代码自动生成API文档。

  虽然这些文档注释规范不是Java语言正式的一部分，但它们已经构成了没个程序猿都应该知道的API。这些规范在*关于如何编写文档注释（How to Write Doc Comments）*的网页上进行了说明[Javadocguide]。虽然这个网页在Java 4发行之后就没有再进行更新了，但它仍然是个很有价值的资源。Java 9中添加了一个重要的doc标签，{@index}; Java 8中添加了一个，{@implSpec}; Java 5中添加了两个，{@literal}和{@code}。上述网页中没有这些标签，但在此项中进行了【相关的】讨论。

  为了正确地编写API文档，必须在没个被导出的类、接口、构造器、方法和域声明之前增加一个文档注释。 如果类是可序列化的，也应该对它的序列化形式编写文档（第87项）。在没有文档注释的情况下，Javadoc所能够做的也就是重新生成该声明，作为受影响的API元素的唯一文档。使用没有文档注释的API是非常痛苦的，也很容易出错。公共类不应使用默认构造函数，因为无法为它们提供文档注释。为了编写可维护的代码，你还应该为大多数未导出的类，接口，构造函数，方法和字段编写文档注释，尽管这些注释不需要像导出的API元素那样详细。

  方法的文档注释应该简洁地描述它和客户端之间的约定。 除了专门为了继承而设计的类中的方法（第19项）之外，这个约定应该说明这个方法做了什么，而不是说明它是如何完成这项工作的。文档注释应该列举出这个方法的所有前提条件（preconditions），这些条件是客户端调用它的必要条件，以及它的后置条件（postconditions），这些条件是调用成功后会成立的事情【就是调用成功后会发生什么事情】。一般情况下，前提条件是由@throw标签针对未受检的异常所隐含描述的；每个未受检的异常都对应一个违背前提条件的例子（precondition violation）。同样的，也可以在一些受影响的参数的@Param标记中指定前提条件。

  除了前提条件和后置条件之外，没个方法还应该在文档中描述它的副作用（side effects）。所谓副作用是指系统状态中可以观察到的变化，它不是为了获得后置条件而明确要求的变化。例如，如果方法启动了后台线程，文档中就应该说明这一点。

  为了完整地描述方法的约定，文档注释应该为每个参数都使用一个@Param标记，方法使用@return标记，除非方法的返回类型是void，以及对于该方法抛出的每个异常，无论是受检的还是未受检的，都有一个@throws标签（第74项）。如果@return标签的文本内容和方法的描述相同，则可以省略它，具体取决于你遵循的编码标准。

  按照惯例，跟在@param标签或者@return标签后面的文字应该是一个名词短语，描述了这个参数或者返回值所表示的值。很少使用算术表达式代替名词短语；请参阅BigInteger的示例。跟在@throw标签之后的文字应该包含单词“if”（如果），后面跟着一个子句（clause），它描述了这个异常将在什么样的条件下会被抛出。按照惯例，@param，@return或@throws标签之后的短语或子句不会以句号为结尾。下面这个文档注释演示了所有这些习惯的做法：

/**
* Returns the element at the specified position in this list.
*
* <p>This method is <i>not</i> guaranteed to run in constant
* time. In some implementations it may run in time proportional
* to the element position.
*
* @param index index of element to return; must be
*        non-negative and less than the size of this list
* @return the element at the s