要想使一个API真正可用,就必须为其编写文档。Java提供了Javadoc工具,使得为API编写文档变得非常容易。Javadoc利用特殊格式的文档注释,根据源代码自动生成API文档。
示例:
/**
* 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 specified position in this list
* @throws IndexOutOfBoundsException if the index is out of range
* ({@code index < 0 || index >= this.size()})
*/
E get(int index);