JavaDoc 书写规范

在Java程序中正确使用javadoc标记是一个良好的注释习惯，将非常有助于javadoc自动从源代码文件生成完整的格式化API文档。下面就对各种标记进行详细说明。

◇ @author name-text 指定生成文档中的作者项，从JDK/SDK 1.0开始引入。name-text可以指定多个名字（使用,隔开）。文档注释可以包含多个类。

◇ {@docroot} 代表产生文档的根路径，从JDK/SDK 1.3开始引入。用法举例如下

/**

*see the <a href={@docroot}/copyright.html>copyright</a>

"*/

假定生成文档的根目录是doc，上面注释所在的文件最后生成的文件是doc\utility\utl.html，那么"copyright"的链接会指向..\copyright.html。

◇ @deprecated deprecated-text 添加注释，表明不推荐使用该API。

◇ @exception class-name description @throw的同义标记，从JDK/SDK 1.0开始引入。

◇ {@link package.class#member label} 插入指向package.class#member的内嵌链接，从JDK/SDK 1.2开始引入。举例说明，假定注释中有如下文档：

/** Use the {@link #getComponentAt(int, int) getComponentAt} method. */

那么javadoc最终生成的HTML页面中将有如下内容

Use the <a href = "Component.html#getComponentAt(int,int)" > getComponentAt </a> method.

◇ @param parameter-name description 描述参数，从JDK/SDK 1.0开始引入。

◇ @return description 描述返回值，从JDK/SDK 1.0开始引入。

◇ @see reference 添加"参见"标题，其中有指向reference的链接或者文本项，从JDK/SDK 1.0开始引入。@see标记有三种形式，下面分别说明：

（1）、@see "string" 为"string"添加文本项，不产生链接。

（2）、@see <a href="URL#Value">Label</a> 使用HTML标记产生链接

（3）、@see package.class#member Label 使用Java语言的名字package.class #member产生链接。

◇ @serial field-description 用于缺省可序列化域的注释，从JDK/SDK 1.2开始引入。

◇ @serialField field-name field-type field-description 建立Serializable类的serialPersistentFields成员的ObjectStreamField组件的文档，从JDK/SDK 1.2开始引入。

◇ @serialData data-description data-description建立数据序列和类型的文档，从JDK/SDK 1.2开始引入。

◇ @since since-text 利用since-text内容为文档增加"since"标题，从JDK/SDK 1.1开始引入。

◇ @throws class-name description 与@exception同义。用class-name和description为输出文档添加"抛出"标题，从JDK/SDK 1.2开始引入。

◇ @version version-text 添加"版权"标题，从JDK/SDK 1.0开始引入。

上面介绍了标准doclet提供的所有标记。不过，需要注意这些标记的使用是有位置限制的。其中可以出现在类或者接口文档注释中的标记有：@see、{@link}、@since、@deprecated、@author、@version。可以出现在方法或者构造器文档注释中的标记有：@see、{@link}、@since、@deprecated、@param、@return、@throws、@exception、@serialData。可以出现在域文档注释中的有：@see、{@link}、@since、@desprecated、@serial、@serialField。

除了javadoc自身提供的标准标记以外，我们可以定制自己的标记吗？当然可以。只需要对javadoc标准的doclet程序进行扩充即可。实际上，利用javadoc提供的doclet API，不仅可以扩充doclet标记，甚至还可以改变javadoc的整个输出。为了满足需要，你可以使javadoc输出普通文本、XML文件等。由于扩充doclet涉及到Java编程，本文不再做深入介绍。

总之，javadoc提供了完整规范的API文档功能。在软件项目管理中，合理地使用javadoc不仅可以减少开发时的文档工作量，提高效率；而且还非常有利于将来软件的修改和维护。