javadoc入门

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

java注释

java里面有两种类型的注释。一种是以“/*”起头，以“*/”结尾，并可以跨越多行的注释，如下：

/*
 * 这是一段注释，
 * 它跨越了多行
 */

另一种是以“//”开头的注释，也叫单行注释，格式如下：

// 这是一个单行注释

注释文档

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

对于java语言，最体贴的一项设计就是人们也需要考虑程序的文档化问题。而对程序的文档化，最大的问题莫过于对文档的维护。若文档与代码分离，那么每次改变代码后都要改变文档，这无疑会变成相当麻烦的一件事情。解决的方法看起来似乎很简单：将代码同文档“链接”起来。为达到这个目的，最简单的方法是将所有内容都置于同一个文件。然而，为使一切都整齐划一，还必须使用一种特殊的注释语法，以便标记出特殊的文档；另外还需要一个工具，用于提取这些注释，并按有价值的形式将其展现出来。这些都是Java必须做到的。
用于提取注释的工具叫作javadoc。它采用了部分来自Java编译器的技术，查找我们置入程序的特殊注释标记。它不仅提取由这些标记指示的信息，也将毗邻注释的类名或方法名提取出来。这样一来，我们就可用最轻的工作量，生成十分专业的程序文档。
javadoc输出的是一个HTML文件，可用自己的Web浏览器查看。该工具允许我们创建和管理单个源文件，并生动生成有用的文档。由于有了javadoc，所以我们能够用标准的方法创建文档。而且由于它非常方便，所以我们能轻松获得所有Java库的文档。

javadoc案例

【实验环境】

MyEclipse 10.0 + jdk 1.6.0_13

【实验步骤】

一、新建一个java项目doc。

二、新建一个java文件org.hbin.JavaDocTest.java，并添加类注释。如下图：

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

命令如下：

> javadoc org/hbin/JavaDocTest.java

运行效果如下图：

刷新项目，生成的文档目录结构如下：

此时，文档与源码混在一起，不便于管理维护。可以添加-d参数来指定输出文件的目标目录。

命令如下：

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

如下图：

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

四、参考以上三个步骤，你已经可以生成自己的注释文档了。但如果你的注释中包含中文或其他非英文字符，那么它可能会乱码的。此时，可以通过-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