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、一般的：

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

* @return 

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

* @author

* @version

* @see

* @since

* @serial 

* @deprecated

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

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

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

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

@see Class#field或@see Class.field

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

3、 HTML代码的使用

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

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

表示段落

表示自动标号

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

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

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

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

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

六、其它。

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