斌斌 (给我写信)
原创博文（http://blog.csdn.net/binbinxyz），转载请注明出处！

java凝视

java里面有两种类型的凝视。一种是以“/*”起头，以“*/”结尾。并能够跨越多行的凝视。例如以下：

/*

 * 这是一段凝视。

 * 它跨越了多行

 */

还有一种是以“//”开头的凝视。也叫单行凝视，格式例如以下：

// 这是一个单行凝视

凝视文档

注：本节内容摘自java编程思想第四版2.8.1凝视文档章节

对于java语言，最体贴的一项设计就是人们也须要考虑程序的文档化问题。

而对程序的文档化。最大的问题莫过于对文档的维护。若文档与代码分离。那么每次改变代码后都要改变文档，这无疑会变成相当麻烦的一件事情。解决办法看起来似乎非常easy：将代码同文档“链接”起来。为达到这个目的，最简单的方法是将全部内容都置于同一个文件。然而，为使一切都整齐划一，还必须使用一种特殊的凝视语法，以便标记出特殊的文档；另外还须要一个工具，用于提取这些凝视，并按有价值的形式将其展现出来。这些都是Java必须做到的。

用于提取凝视的工具叫作javadoc。它採用了部分来自Java编译器的技术。查找我们置入程序的特殊凝视标记。

它不仅提取由这些标记指示的信息，也将毗邻凝视的类名或方法名提取出来。

这样一来，我们就可用最轻的工作量，生成十分专业的程序文档。

javadoc输出的是一个HTML文件，可用自己的Web浏览器查看。该工具同意我们创建和管理单个源文件，并生动生成实用的文档。因为有了javadoc。所以我们可以用标准的方法创建文档。并且因为它很方便，所以我们能轻松获得全部Java库的文档。

javadoc案例

【实验环境】

MyEclipse 10.0 + jdk 1.6.0_13

【实验步骤】

一、新建一个java项目doc。

二、新建一个java文件org.hbin.JavaDocTest.java。并加入类凝视。例如以下图：

watermark/2/text/aHR0cDovL2Jsb2cuY3Nkbi5uZXQvYmluYmlueHl6/font/5a6L5L2T/fontsize/400/fill/I0JBQkFCMA==/dissolve/70/gravity/SouthEast" alt="">

三、在命令行工具中打开该项目src所在路径，使用javadoc命令导出java文档凝视。

命令例如以下：

> javadoc org/hbin/JavaDocTest.java

执行效果例如以下图：

刷新项目。生成的文档文件夹结构例如以下：

此时。文档与源代码混在一起。不便于管理维护。能够加入-d參数来指定输出文件的目标文件夹。

命令例如以下：

> javadoc -d ../doc org/hbin/JavaDocTest.java

例如以下图：

watermark/2/text/aHR0cDovL2Jsb2cuY3Nkbi5uZXQvYmluYmlueHl6/font/5a6L5L2T/fontsize/400/fill/I0JBQkFCMA==/dissolve/70/gravity/SouthEast" alt="">

此时。打开项目中doc文件夹下的index.html文件就可以看到我们刚刚生成的文档结构。例如以下图：

watermark/2/text/aHR0cDovL2Jsb2cuY3Nkbi5uZXQvYmluYmlueHl6/font/5a6L5L2T/fontsize/400/fill/I0JBQkFCMA==/dissolve/70/gravity/SouthEast" alt="">

四、參考以上三个步骤，你已经能够生成自己的凝视文档了。但假设你的凝视中包括中文或其它非英文字符，那么它可能会乱码的。此时。能够通过-charset和-encoding參数来指定编码。-charset參数指定查看生成html的编码，即在html文档中加入<META http-equiv="Content-Type" content="text/html; charset=UTF-8">。而-encoding參数指定源文件编码。

命令例如以下：

> javadoc -charset UTF-8 -encoding UTF-8 -d ../doc org/hbin/JavaDocTest.java

watermark/2/text/aHR0cDovL2Jsb2cuY3Nkbi5uZXQvYmluYmlueHl6/font/5a6L5L2T/fontsize/400/fill/I0JBQkFCMA==/dissolve/70/gravity/SouthEast" alt="">