前言
一. Java 文档?javadoc
? 文档注释的格?/font>
1. 文档注释的格式化
2. 文档注释的三部分
? 使用 javadoc 标记
http://outinn.diy.myrice.com/book/javadoc/#t31
http://outinn.diy.myrice.com/book/javadoc/#t32
http://outinn.diy.myrice.com/book/javadoc/#t33
? javadoc 命o(h)
Java 的语法与 C++ ?qing)?f)怼Q那么，你知?Java 的注释有几种吗？是两U？
// 注释一?br /> /* ...... */ 注释若干?/p>
不完全对Q除了以上两U之外，q有W三U，文档注释Q?/p>
/** ...... */ 注释若干行，q写?javadoc 文档
通常q种注释的多行写法如下：(x)
/**
* .........
* .........
*/
暂停Q暂停！q第三种注释有什么用Qjavadoc 又是什么东西？
好，那就让我告诉你—?
Java E序员都应该知道使用 JDK 开发，最好的帮助信息来?SUN 发布?Java 文档。它分包、分c详l的提供了各Ҏ(gu)、属性的帮助信息Q具有详l的cL(wi)信息、烦引信息等Qƈ提供了许多相关类之间的关p，如ѝ实现接口、引用等?/p>
Java 文档全是׃?html 文gl织h的，?SUM 的站点上可以下蝲它们的压~包。但是你肯定想不刎ͼq些文档我们可以自己生成。——就此打住，再吊一ơ胃口?/p>
安装?JDK 之后Q安装目录下有一?src.jar 文g或?src.zip 文gQ它们都是以 ZIP 格式压羃的，可以使用 WinZip 解压。解压之后，我们可以看到分目录攄全是 .java 文g。是了，q些是 Java q行cȝ源码了，非常完整Q连注释都写得一清二楚……不q，怎么看这些注释都有点似曾相识的感觉？
q就不奇怪了Q我们的q底也快要揭开了。如果你仔细Ҏ(gu)一?.java 源文件中的文档注?(/** ... */) ?Java 文档的内容，你会(x)发现它们是一L(fng)。Java 文档只是q在格式和排版上下了些功夫。再仔细一点，你会(x)发现 .java 源文件中的注释还带有 HTML 标识Q如 <B>?lt;BR>?lt;Code> {，?Java 文档中，该出现这些标识的地方Q已l按标识的的定义q行了排版?/p>
l于真像大白了，原来 Java 文档是来自这些注释。难怪这些注释叫做文档注释呢Q不q，是什么工hq些注释变成文档的呢Q?/p>
是该请出 javadoc 的时候了。在 JDK ?bin 目录下你可以扑ֈ javadocQ如果是 Windows 下的 JDKQ它的文件名?javadoc.exe。?javdoc ~译 .java 源文件时Q它?x)读?.java 源文件中的文档注释，q按照一定的规则?Java 源程序一赯行编译，生成文档?/p>
介绍 javadoc 的编译命令之前，q是先了解一下文档注释的格式吧。不qؓ(f)了能够编译下面提到的若干例子Q这里先介绍一?javadoc 命o(h)Q?/p>
javadoc -d 文档存放目录 -author -version 源文件名.java
q条命o(h)~译一个名?“源文g?java”的 java 源文Ӟq将生成的文档存攑֜“文档存攄录”指定的目录下，生成的文档中 index.html 是文档的首c(din)?author ?-version 两个选项可以省略?/p>
文档注释可以用于对类、属性、方法等q行说明。写文档注释旉了需要?/** .... */ 限定之外Q还需要注意注释内部的一些细节问题?/p>
生成的文档是 HTML 格式Q而这?HTML 格式的标识符q不?javadoc 加的Q而是我们在写注释的时候写上去的。比如，需要换行时Q不是敲入一个回车符Q而是写入 <br>Q如果要分段Q就应该在段前写?<p>?/p>
因此Q格式化文档Q就是在文档注释中添加相应的 HTML 标识?/p>
文档注释的正文ƈ不是直接复制到输出文?(文档?HTML 文g)Q而是d每一行后Q删掉前导的 * 号及(qing) * 号以前的I格Q再输入到文档的。如
|
/** * This is first line. <br> ***** This is second line. <br> This is third line. */ |
~译输出后的 HTML 源码则是
| This is first line. <br> This is second line. <br> This is third line. |
前导?* 号允许连l用多个，其效果和使用一?* 号一P但多?* 号前不能有其它字W分隔，否则分隔W及(qing)后面?* 号都作为文档的内容? 号在q里是作为左边界使用Q如上例的第一行和W二行；如果没有前导?* P则边界从W一个有效字W开始，而不包括前面的空|如上例第三行?/p>
q有一炚w要说明，文档注释只说明紧接其后的cR属性或者方法。如下例Q?/p>
/** comment for class */
public class Test {
/** comment for a attribute */
int number;
/** comment for a method */
public void myMethod() { ...... }
......
}
|
上例中的三处注释是分别对类、属性和Ҏ(gu)的文档注释。它们生成的文档分别是说明紧接其后的cR属性、方法的。“紧接”二字尤光要，如果忽略了这一点，很可能造成生成的文档错误。如
import java.lang.*;
/** commnet for class */
public class Test { ...... }
// 此例为正的例子
|
q个文档注释生成正的文档。但只需要改变其中两行的位置Q变成下例，׃(x)出错Q?/p>
/** commnet for class */
import java.lang.*;
public class Test { ...... }
// 此例为错误的例子
|
q个例子只把上例?import 语句和文档注释部分交换了位置Q结果却大不相同——生成的文档中根本就找不Cq注释的内容了。原因何在？
?font color="#008000">/** commnet for class */”是?class Test 的说明，把它攑֜“public class Test { ...... }”之前时Q其后紧接着 class TestQ符合规则，所以生成的文档正确。但是把它和“import java.lang.*;”调换了位置后，其后紧接的就是不 class Test 了，而是一?import 语句。由于文档注释只能说明类、属性和Ҏ(gu)Qimport 语句不在此列Q所以这个文档注释就被当作错误说明省略掉了?/p>
Ҏ(gu)在文档中昄的效果，文档注释分ؓ(f)三部分。先举例如下Q以便说明?/p>
/**
* show Ҏ(gu)的简q?
* <p>show Ҏ(gu)的详l说明第一?lt;br>
* show Ҏ(gu)的详l说明第二行
* @param b true 表示昄Qfalse 表示隐藏
* @return 没有q回?
*/
public void show(boolean b) {
frame.show(b);
}
|
W一部分是简q。文档中Q对于属性和Ҏ(gu)都是先有一个列表，然后才在后面一个一个的详细的说明。列表中属性名或者方法名后面那段说明是q。如下图中被U框框选的部分Q?/p>
q部分写在一D|档注释的最前面Q第一个点?(.) 之前 (包括点号)。换句话_(d)是用第一个点号分隔文档注释，之前是简qͼ之后是第二部分和W三部分。如上例中的 ? show Ҏ(gu)的简q?”?/p>
有时Q即使正地以一个点号作为分隔，javadoc 仍然?x)出错，把点号后面的部分也做ZW一部分。ؓ(f)了解册个问题，我们可以使用一?<p> 标志第二分部分开Z一D，如上例的? <p>show Ҏ(gu)的详l说明第一?....”。除此之外，我们也可以?<br> 来分隔?/p>
W二部分是详l说明部分。该部分对属性或者方法进行详l的说明Q在格式上没有什么特D的要求Q可以包含若q个点号。它在文档中的位|如下图所C：(x)
q部分文档在上例中相应的代码是：(x)
* show Ҏ(gu)的简q?
* <p>show Ҏ(gu)的详l说明第一?lt;br>
* show Ҏ(gu)的详l说明第二行
发现什么了Q对了，qC在其中。这一点要C了，不要画蛇添——在详细说明部分中再写一ơ简q哦Q?/p>
W三部分是特D说明部分。这部分包括版本说明、参数说明、返回D明等。它在文档中的位|：(x)
W三部分在上例中相应的代码是
* @param b true 表示昄Qfalse 表示隐藏
* @return 没有q回?/font>
除了 @param ?@return 之外Q还有其它的一些特D标讎ͼ分别用于对类、属性和Ҏ(gu)的说明……不要推我，我马上就说?/p>
javadoc 标记是插入文档注释中的特D标讎ͼ它们用于标识代码中的Ҏ(gu)引用。javadoc 标记由“@”及(qing)其后所跟的标记cd和专用注释引用组成。记住了Q三个部分——@、标记类型、专用注释引用。不q我宁愿把它分成两部分：(x)@ 和标记类型、专用注释引用。虽?@ ?标记cd之间有时可以用空格符分隔Q但是我宁愿始终它们紧挨着写，以减出错机?x)?/p>
javadoc 标记有如下一些：(x)
|
下面详细说明各标记?/p>
@see 的句法有三种Q?
@see cd
@see #Ҏ(gu)名或属性名
@see cd#Ҏ(gu)名或属性名
cdQ可以根据需要只写出cd (?String) 或者写出类全名 (?java.lang.String)。那么什么时候只需要写出类名，什么时候需要写出类全名呢？
如果 java 源文件中?import 语句包含了的c，可以只写出类名，如果没有包含Q则需要写出类全名。java.lang 也已l默认被包含了。这?javac ~译 java 源文件时的规定一P所以可以简单的?javac ~译来判断，源程序中 javac 能找到的c，javadoc 也一定能扑ֈQjavac 找不到的c，javadoc 也找不到Q这需要用类全名了?/p>
Ҏ(gu)名或者属性名Q如果是属性名Q则只需要写出属性名卛_Q如果是Ҏ(gu)名，则需要写出方法名以及(qing)参数cdQ没有参数的Ҏ(gu)Q需要写ZҎ(gu)受如
| 成员cd | 成员名称?qing)参?/b> | @see 句法 |
| 属?/td> | number | @see number |
| 属?/td> | count | @see count |
| Ҏ(gu) | count() | @see count() |
| Ҏ(gu) | show(boolean b) | @see show(boolean) |
| Ҏ(gu) | main(String[] args) | @see main(String[]) |
有时也可以偷懒：(x)假如上例中，没有 count q一属性，那么参考方?count() 可以简写成 @see count。不q，Z安全赯Q还是写?@see count() 比较好?/p>
@see 的第二个句法和第三个句法都是转向Ҏ(gu)或者属性的参考，它们有什么区别呢Q?/p>
W二个句法中没有指出cdQ则默认为当前类。所以它定义的参考，都{向本cM的属性或者方法。而第三个句法中指ZcdQ则q可以{向其它类的属性或者方法?/p>
关于 @see 标记Q我们D个例说明。由?@see 在对c说明、对属性说明、对Ҏ(gu)说明时用法都一P所以这里只以对c说明ؓ(f)例?/p>
/**
* @see String
* @see java.lang.StringBuffer
* @see #str
* @see #str()
* @see #main(String[])
* @see Object#toString()
*/
public class TestJavaDoc {
}
|
生成的文档的相关部分如下图：(x)
String ?StringBuffer 都是?java.lang 包中Q由于这个包是默认导入了的，所以这两个cd以直接写cdQ也可以写类全名。str、str() 为同名属性和Ҏ(gu)Q所以方法名需要用 () 区分。main 是带参数的方法，所以在 () 中指明了参数cd。toString() 虽然在本cM也有 (?Object l承?Q但我们是想参?Object cȝ toString() Ҏ(gu)Q所以用了 Object#toString()?/p>
奇怪的是，Z么其中只?str、str() ?main(String[]) 变成了链接呢Q那是因为编译时没有?java.lang 包或?Stirng、StringBuffer、Object 三个cȝ源文件一起加入编译，所以，生成的文档没有关于那三个cȝ信息Q也׃可以建立链接了。后面讲?javadoc ~译命o(h)的时候还?x)详l说明?/p>
上例中如果去把类中的 str 属性去掉，那么生成的文档又?x)有什么变化呢Q你?x)发玎ͼ原来?str, str()Q而现在变成了 str(), str()Q因?str 属性已l没有了Q所?str 也表C方?str()?/p>
2. 使用 @author、@version 说明c?/p>
q两个标记分别用于指明类的作者和版本。缺省情况下 javadoc 其忽略Q但命o(h)行开?-author ?-version 可以修改q个功能Q其包含的信息被输出。这两个标记的句法如下：(x)
@author 作者名
@version 版本?/font>
其中Q@author 可以多次使用Q以指明多个作者，生成的文档中每个作者之间用逗号 (,) 隔开。@version 也可以用多ơ，只有W一ơ有效，生成的文档中只会(x)昄W一ơ?@version 指明的版本号。如下例
/**
* @author Fancy
* @author Bird
* @version Version 1.00
* @version Version 2.00
*/
public class TestJavaDoc {
}
|
生成文档的相关部分如图：(x)
从生成文档的囄中可以看出，两个 @author 语句都被~译Q在文档中生成了作者列表。而两?@version 语句中只有第一句被~译了，只生成了一个版本号?/p>
从图上看Q作者列表是以逗号分隔的，如果我想分行昄怎么办？另外Q如果我xCZ个以上的版本号又该怎么办？
——我们可以将上述两条 @author 语句合ؓ(f)一句，把两?@version 语句也合Z句：(x)
@author Fancy<br>Bird
@version Version 1.00<br>Version 2.00
l果如图Q?/p>
我们q样做即辑ֈ了目的，又没有破坏规则。@author 之后的作者名?@version 之后的版本号都可以是用户自己定义的Q?HTML 格式Q所以我们可以?<br> 标记其分行昄。同Ӟ在一?@version 中指明两个用 <br> 分隔的版本号Q也没有破坏只显C第一?@version 内容的规则?/p>
3. 使用 @param、@return ?@exception 说明Ҏ(gu)
q三个标记都是只用于Ҏ(gu)的。@param 描述Ҏ(gu)的参敎ͼ@return 描述Ҏ(gu)的返回|@exception 描述Ҏ(gu)可能抛出的异常。它们的句法如下Q?/p>
@param 参数?参数说明
@return q回D?br /> @exception 异常cd 说明
每一?@param 只能描述Ҏ(gu)的一个参敎ͼ所以，如果Ҏ(gu)需要多个参敎ͼ需要多ơ?@param 来描q?/p>
一个方法中只能用一?@returnQ如果文档说明中列了多个 @returnQ则 javadoc ~译时会(x)发出警告Q且只有W一?@return 在生成的文档中有效?/p>
Ҏ(gu)可能抛出的异常应当用 @exception 描述。由于一个方法可能抛出多个异常，所以可以有多个 @exception。每?@exception 后面应有q的异常cdQ说明中应指出抛出异常的原因。需要注意的是，异常cd应该Ҏ(gu)源文件的 import 语句定是写出类名还是类全名? CZ如下Q?/p>
public class TestJavaDoc {
/**
* @param n a switch
* @param b excrescent parameter
* @return true or false
* @return excrescent return
* @exception java.lang.Exception throw when switch is 1
* @exception NullPointerException throw when parameter n is null
*/
public boolean fun(Integer n) throws Exception {
switch (n.intValue()) {
case 0:
break;
case 1:
throw new Exception("Test Only");
default:
return false;
}
return true;
}
}
|
使用 javadoc ~译生成的文档相关部分如下图Q?/p>
可以看到Q上例中 @param b excrescent parameter 一句是多余的，因ؓ(f)参数只是一?nQƈ没有一?b但?javadoc ~译时ƈ没有(g)查。因此，写文档注释时一定要正确匚w参数表与Ҏ(gu)中正式参数表的项目。如果方法参数表中的参数?aQ文档中却给出对参数 x 的解释，或者再多出一个参?iQ就?x)让人摸不着头脑了。@exceptin 也是一栗?/p>
上例E序中ƈ没有抛出一?NullPointerExceptionQ但是文档注释中Z么要写上q么一句呢Q难道又是ؓ(f)了演C？q不是ؓ(f)了演C描q多余的异常也能通过~译Q而是Z说明写异常说明时应考运行时 (RunTime) 异常的可能性。上例程序中Q如果参?n 是给的一个空?(null)Q那么程序会(x)在运行的时候抛Z?NullPointerExceptionQ因此，在文档注释中d了对 NullPointerException 的说明?/p>
上例中的 @return 语句有两个，但是Ҏ(gu)规则Q同一个方法中Q只有第一?@return 有效Q其余的?x)?javadoc 忽略。所以生成的文档中没有出现第二个 @return 的描q?/p>
讲到q里Q该怎么写文档注释你应该已经清楚了，下面开始讲?javadoc 的常用命令?/p>
q行 javadoc -help 可以看到 javadoc 的用法，q里列D常用参数如下Q?/p>
用法Q?br /> javadoc [options] [packagenames] [sourcefiles]
选项Q?/p>
| -public | 仅显C?public cd成员 | |
| -protected | 昄 protected/public cd成员 (~省) | |
| -package | 昄 package/protected/public cd成员 | |
| -private | 昄所有类和成?/td> | |
| -d <directory> | 输出文g的目标目?/td> | |
| -version | 包含 @version D?/td> | |
| -author | 包含 @author D?/td> | |
| -splitindex | 烦引分为每个字母对应一个文?/td> | |
| -windowtitle <text> | 文档的浏览器H口标题 |
javadoc ~译文档时可以给定包列表Q也可以l出源程序文件列表。例如在 CLASSPATH 下有两个包若q类如下Q?/p>
fancy.Editor
fancy.Test
fancy.editor.ECommand
fancy.editor.EDocument
fancy.editor.EView
q里有两个包 (fancy ?fancy.editor) ?5 个类。那么编译时 (Windows 环境) 可以使用如下 javadoc 命o(h)Q?/p>
javadoc fancy\Test.java fancy\Editor.java fancy\editor\ECommand.java fancy\editor\EDocument.java fancy\editor\EView.java
q是l出 java 源文件作为编译参数的Ҏ(gu)Q注意命令中指出的是文g路径Q应该根据实际情冉|变。也可以是给出包名作为编译参敎ͼ如：(x)
javadoc fancy fancy.editor
用浏览器打开生成文档?index.html 文g卛_发现两种方式~译l果的不同，如下图：(x)
用第二条命o(h)生成的文档被框架分成了三部分Q包列表、类列表和类说明。在包列表中选择了某个包之后Q类列表中就?x)列包中的所有类Q在cd表中选择了某个类之后Q类说明部分׃(x)昄cȝ详细文档。而用W一条命令生成的文档只有两部分，cd表和c说明，没有包列表。这是两种方式生成文档的最大区别了?/p>
下面再来l说选项?/p>
-public?protected?package?private 四个选项Q只需要Q选其一卛_。它们指定的昄cL员的E度。它们显C的成员多少是一个包含的关系Q如下表Q?/p>
| -private (昄所有类和成? | |||||
|
-d 选项允许你定义输出目录。如果不?-d 定义输出目录Q生成的文档文g?x)放在当前目录下?d 选项的用法是
-d 目录?/font>
目录名ؓ(f)必填，也就是说Q如果你使用?-d 参数Q就一定要为它指定一个目录。这个目录必dl存在了Q如果还不存在，请在q行 javadoc 之前创徏该目录?/p>
-version ?-author 用于控制生成文档时是否生?@version ?@author 指定的内宏V不加这两个参数的情况下Q生成的文档中不包含版本和作者信息?/p>
-splitindex 选项烦引分为每个字母对应一个文件。默认情况下Q烦引文件只有一个，且该文g中包含所有烦引内宏V当然生成文档内容不多的时候，q样做非常合适，但是Q如果文档内定w常多的时候，q个索引文g包含非常多的内容，昑־q于庞大。?-splitindex ?x)把索引文g按各索引的W一个字母进行分c，每个字母对应一个文件。这P减M一个烦引文件的负担?/p>
-windowtitle 选项为文档指定一个标题，该标题会(x)昄在窗口的标题栏上。如果不指定该标题，而默认的文档标题为“生成的文档Q无标题Q”。该选项的用法是Q?/p>
-windowtitle 标题
标题是一串没有包含空格的文本Q因为空格符是用于分隔各参数的，所以不能包含空根{同 -d cMQ如果指定了 -windowtitle 选项Q则必须指定标题文本?/p>
到此为止QJava 文档?javadoc ׃l完了。javadoc 真的能让我们?Java 注释上做文章——生成开发文档?/p>
<input type="text" name="firstname" id="tfield" onblur="if (this.value) {doSomething();}" />而如果是文本区域,文本输入块的话就?
<textarea name="tarea" rows="20" id="question" cols="20" onblur="if (this.value) {doSomething();}">如果输入框ؓ(f)I的?JavaScript ?x)?this.value 解析?false, 所以后面的doSomething()不?x)执行?br />JavaScript 表单中的空白字D计ؓ(f)I字W串或?amp;& 。this 关键字是指向包含事g处理属性（如：(x)blurQ?br />的表单输入框的很好而常用的Ҏ(gu)。而this.value 则返回这个文本输入框的内宏V?br />
]]>
if (document.implementation
&& document.implementation.createDocument){
xDoc=document.implementation
.createDocument("","",null);
}else if (typeof ActiveXObject != "undefined"){
var msXmlAx==null;
try{
msXmlAx=new ActiveXObject
("Msxml2.DOMDocument");
}catch (e){
msXmlAx=new ActiveXObject
("Msxml.DOMDocument");
}
xDoc=msXmlAx;
}
if (xDoc==null || typeof xDoc.load=="undefined"){
xDoc=null;
}
return xDoc;
}
function getXMLHTTPRequest() {
var xRequest=null;
if (window.XMLHttpRequest) {
xRequest=new XMLHttpRequest();
}else if (typeof ActiveXObject != "undefined"){
xRequest=new ActiveXObject
("Microsoft.XMLHTTP");
}
return xRequest;
}
]]>