JavaDoc文档编写学习

JavaDoc文档编写

一、据说文档编写在实际项目工程中非常重要，所以要好好学习一下。

JavaDoc.exe会根据代码中的文档注释，自动生成对应的HTML文档，所以文档要按规定的格式来写，才能生成正确的文档。而且文档注释也应该尽量全面。

注释文档会 生成的JavaDoc文档和在代码中生成辅助信息（鼠标停留在使用的位置处，就会显示注释文档）。文档注释内容会按@的类别在HTML

或辅助信息中分类显示出来和进行各种跳转等。

二、注释文档的格式。

1、/**

*xxxxxxx

*@xxx xxx

*加上/** */这种格式后，这里面就表示文档注释。

*/

要写在类或接口，域，方法，成员的前面。

文档注释分两部分，描述、块标记。描述就是关于这个构件的描述，块标记用”@XXX  描述 “来表示，描述了此构件某一方面的信息。

百度百科上的

常用标记

标签说明JDK 1.1 doclet标准doclet标签类型@author 作者作者标识√√包、 类、接口@version 版本号版本号√√包、 类、接口@param 参数名 描述方法的入参名及描述信息，如入参有特别要求，可在此注释。√√构造函数、 方法@return 描述对函数返回值的注释√√方法@deprecated 过期文本标识随着程序版本的提升，当前API已经过期，仅为了保证兼容性依然存在，以此告之开发者不应再用这个API。√√包、类、接口、值域、构造函数、 方法@throws异常类名构造函数或方法所会抛出的异常。 √构造函数、 方法@exception 异常类名同@throws。√√构造函数、 方法@see 引用查看相关内容，如类、方法、变量等。√√包、类、接口、值域、构造函数、 方法@since 描述文本API在什么程序的什么版本后开发支持。√√包、类、接口、值域、构造函数、 方法{@link包.类#成员 标签}链接到某个特定的成员对应的文档中。 √包、类、接口、值域、构造函数、 方法{@value}当对常量进行注释时，如果想将其值包含在文档中，则通过该标签来引用常量的值。 √(JDK1.4)静态值域

三、各种构件如何使用文档注释。

大的构件包含小的，大的注释过的部分，那么小的就不必再注释了。比如对类注释了版本方法就不必再注释了。

1、类、接口的注释块标记部分必须注明作者和版本。

2、构造函数注释主要描述部分注明构造函数的作用。

3、方法注释，描述部分注明方法的功能，块标记部分注明方法的参数，返回值，异常等信息

四、注释的顺序。

1、一般的：

* @param  在描述中第一个名字为该变量的数据类型，表示数据类型的名次前面可以有一个冠词如：a,an,the。

* @return 

* @exception jdk较高版本使用的@throw

* @author

* @version

* @see

* @since

* @serial 

* @deprecated

2、一个块标记可以根据需要重复出现多次，多次出现的标记按照如下顺序：

@author 按照时间先后顺序（chronological）

@param 按照参数定义顺序（declaration）

@throws 按照异常名字的字母顺序（alphabetically）

@see 按照小构件到大构件的顺序：@see #field或@see  #method(Type, Type,...)或@see Class#field或@see Class.field

 @since 标明该类可以运行的JDK版本

3、 HTML代码的使用

既然是HTML就可以使用HTML咯。

在注释描述部分可以使用HTML代码。

表示段落

表示自动标号

参考：http://blog.csdn.net/afeilxc/article/details/4060089

五、生成JavaDoc文档，如果在eclipse下使用JavaDoc工具，则比较简单。

选 中项目，右键-》导出-》Java--》JavaDoc-》下一步，配置选项里选择生成JavaDoc所使用的工具。

到jdk安装目录下的bin下的JavaDoc.exe即可，例如C:\Program Files\Java\jdk1.8.0_25\bin\javadoc.exe，

下方可以选择导出的路径，默认是工程下面，然后完成。

到对应路径下面查看JavaDoc即可。

六、其它。

文档注释也能继承，对于某类别的注释还能进行覆盖。类中的成员方法Overview时，文档注释也会继承