为你的JAVA程序自动生成注释文档（JAVADOC）

daxia108

好的程序员是会写文档的程序员，为自己写，也为别人写。有句话说的好：好的代码是别人能够看懂的代码，文档也在交流中起了非常重要的作用。 对于一个让你头大的n行JAVA源程序，你利用生成的java文档可以在很短的时间了解大概。

JavaDoc 是 java 程序员写文档的标准。javadoc 也是一条java命令，可以从你的代码中的注释文档自动生成类似java API document 的HTML文件。

我们在开发JAVA程序中, 可以使用Javadoc来进行程序文档的整理, 当程序编写完成, 利用Java自带的JavaDoc工具就可以生成规范的API说明手册. 下面是一些语法:

书写格式:

/** <- 这里一定要用两个星号, 否则会被认为是普通注释,不能显示在JAVA文档中。

* ........注释内容

*/
public int getCount() { .......

Javadoc只能为public,protected两种权限的类成员进行处理注释文档。当然也可以使用javadoc -private参数强制对所有类成员进行处理, 我们还可以在注释中嵌入HTML个标记来丰富最后文档的显示, 因为Javadoc最后生成的文档就是HTML.


/**
* 一些参数列表<p>
*
* @see －－ 类名
* @see －－ 完整类名
* @see －－ 完整类名#方法
*
* @param －－ 参数名 说明
* @return －－ 返回变量 说明
* @exception －－ 完整类名 说明
* @deprecated
*
* @version －－ 版本信息
* @author －－ 作者名
*/

说明:
@see : 就是文档中的 参见xx 的条目, 其实就是超链接.

一般来说, 文档有三种类型: 类注释, 变量注释, 方法注释, 这三中类型的注释除了都可以包含 @see 参数外, 其它所包含的参数是不同的.
1. 类注释
类注释是写在类前面的, 用来说明类的一些情况, 可以包涵 @version,@author参数, 但Javadoc缺省情况下不处理, 也就是说不在最后文档中出现的, 为了使用这些信息, 我们可以加入参数 -version和 -author来强制输出到最后的文档中.
2. 变量注释
变量注释写在变量前面, 只能包含 @see 参数
3. 方法注释
方法注释可以包括
@param : 参数名是指参数列表内的标识符, 说明就是一些解释性质的文字, 可以多行.
@return : 返回值的说明, 可以多行
@exception : 完整类名应该明确指定一个违例类的名字，它是在其它某个地方定义好的。而说明则阐述为什么这种特殊类型的违例会在方法调用中出现。说明可以多行
@deprecated : 指出一些旧功能已由改进过的新功能取代。该标记的作用是建议用户不必再使用一种特定的功能，因为未来改版时可能摒弃这一功能。若将一个方法标记为@deprecated，则使用该方法时会收到编译器的警告。

路路

顶上去，还有吗？