计算机二级JAVA技巧:javadoc注释

对于软件工程来说代码的编写并不是重要的事情。文档编写的重要性不亚于程序代码本身。如果代码与文档是分离的，那么在每次修改代码时，都需要修改相应的文档就会是一件相当麻烦的事情。所以我们通过javadoc将代码同文档“连接”起来。

Javadoc是什么？

javadoc是Sun公司提供的一个技术，它从程序源代码中抽取类、方法、成员等注释形成一个和源代码配套的API帮助文档。也就是说，只要在编写程序时以一套特定的标签作注释，在程序编写完成后，通过Javadoc就可以同时形式程序的开发文档了。

Javadoc输出的是一些HTML文件，我们可以通过WEB浏览器来查看它。

Javadoc的语法：

所有Javadoc都只能源于/**开始和*/结束。使用javadoc有二种方式，一种是嵌入HTML另一种是使用文档标签。所谓文档标签就是一些以 “@”开头的命令，且“@”要置于注释行的最前面。而“行内文档标签”则可以出现在Javadoc注释中的任何地方，它们也是以“@”字符开头，但要括在共括号内。

Javadoc只能为public或者protected成员进行文档注释。private和包内访问的成员的注释会被忽略掉。这样做是有道理的，因为只有public和protected成员才能在文件之外被使用，这也体现了封装性的优点。

嵌入HTML:

Javadoc将HTML代码嵌入到所生成的HTML文件中。这样能充分利用HTML的功能。比如：

/**

*

*this is my test program

*

*/

但一般我们不要在HTML里使用标题，如

，因为Javadoc会插入自己的标题，我们的标题可能会干扰它。

一些有用的标签：

1)@see:引用其它类的文档，相当于超链接，Javadoc会在其生成的HTML文件中，将@see标签链到其他的文档

@see classname

这样在生成的文档中会出现"See Also"的超链蛸。但是Javadoc不去检查你的超链接是否有效。

2){@link package.class#member label}

与@See的功能一样，只是用label作主超链接，而不是用"see also"

3){@docRoot}：标签产生 到文档根目录的相对路径，用于文档树页面的显式超链接

4){@inheritDoc}:标签从当前这个类的最直接的基类中继承相关文档到当前的文档注释中。

5)@version：使用方法为@version 2.2.1.2...

2.2.1.2...是我们作的版本说明信息

6)@author:使用方法为 @author PowerFedora powpro@hotmail.com

也就是说我们可以在@author后加上作者名字，email等联系方式

7)@since：这个标签允许你指定程序最早使用的版本。比如我们看JDK Document里的每个类最后都会说明从JDK哪个版本开始启用。

8)@param：@param name 用于输入客户的姓名

@param后面是方法的参数，以及相应的说明

我们可以使用任意数量的此标签，每个参数都可以有这样一个标签

9)@return this is description

@return后面是描述返回值的含义，可以延续几行。

10)@throws fully-qualified-class-name description

fully-qualified-class-name为异常类的完整名字，而description告诉你为什么此异常会在方法中调用出现。

11)@deprecated:用于指出一些旧特性已由改进的新特性所取代，建议用户不要再使用旧特性。

接下来我们用一个代码将上述所有的标签都使用起来，看一下效果：

//: test Javadoc,JavaCode.java

import java.util.*

/** 这是一个为了测试Javadoc而专门写的类

* 功能是打印字符串

* @author PowerFedora

* @author powpro@hotmail.com

* @version 1.0

*/

public class JavaCode {

/** 这里的main函数，作为java程序的入口

* @param 参数为一个String对象数组

* @return 没有返回值的内容

* @exception exceptions 没有异常被抛出

*/

public static void main(String[] args){

String a = "中华人民共和国"

System.out.print(a)

}

} ///:~ 　值得一题的是，如果你使用eclipse的话，完全不需要背这些标签。当我们在需要注释的地方打上/**之后，再打@符号eclipse会自动显示所支持的标签供我们选择。

同样在生成HTML文档时我们也可以利用eclipse的export功能直接导出，否则用javadoc手工来生成的话是件相当痛苦的事情。

以下列出来javadoc支持的参数：

-author

-bootclasspath

-bottom

-breakiterator

-charset

-classpath

-d

-docencoding

-docfilessubdirs

-doclet

-docletpath

-doctitle

-encoding

-exclude

-excludedocfilessubdir

-extdirs

-footer

-group

-header

-help

-helpfile

-J

-keywords

-link

-linkoffline

-linksource

-locale

-nocomment

-nodeprecated

-nodeprecatedlist

-nohelp

-noindex

-nonavbar

-noqualifier

-nosince

-notimestamp

-notree

-overview

-package

-private

-protected

-public

-quiet

-serialwarn

-source

-sourcepath

-splitindex

-stylesheetfile

-subpackages

-tag

-taglet

-tagletpath

-title

-use

-verbose

-version

-windowtitle

工具：

eclipse

方法：

通过菜单 Window->Preference 打开参数设置面板，然后选择：

Java ->Code Style ->Code     Templates

在右侧选择Comments,将其中的Files项，然后选右边的"Edit"，进入编辑模式：   

进入编辑模式后就可以自定义注释了。另外可以插入一些变量，如年、日期等等。

最后，确保 Code ->New Java files 中有："${filecomment}"

当然，通过“导出”和“导入”功能，你可以把自己的模板导出来在其他机器上使用。

右键工程 点击Export 如图 选择javadoc

点击next

如图 设置JDK里面的javadoc.exe的地址 点击finish 到此就可简单生成一个javadoc 前提是你的类里面有类似下图的注释

遇到的问题

1.在使用中文注释的时候 遇到编码 GBK 的不可映射字符这个问题

解决方法 在上面的最后一步中 不要点击finish  一路next到最后一个页面

如图输入-encoding UTF-8 - charset UTF-8即可

2.自定义标签

eclipse自带有几个标签 如@author @version等 如何在doc文档中自动生成自定义的标签呢

只需在上面的对话框中 再添加一句 -tag CreateBy:a:"CreateBy"  其中 CreateBy 为你自定义的标签

---