javadoc的用法

原文地址：http://hi.baidu.com/johnsoncr/item/801e8dfe4ce14dec1b111fb2

只要在/**……*/这么滴诠释才能被写入javadoc文档。
1.java文档和javadoc
在jdk滴bin目录下你可以找到javadoc，如果是windows下滴jdk，它滴文件名为javadoc.exe。运用javdoc编译.java源文件时，它会念出.java源文件中滴文档诠释，并遵照必定滴限定和java源程序一起进展编译，生成文档。
　　引见javadoc滴编译吩咐之前，还是先懂得一下文档诠释滴款式吧。不过为了能够编译下面提到滴若干例子，这里先引见一条javadoc吩咐：
　　javadoc -d 文档寄存目录 -author -version 源文件名.java
　　这条吩咐编译1个名为“源文件名.java”滴java源文件，并将生成滴文档存放在“文档寄存目录”指定滴目录下，生成滴文档中index.html不外乎文档滴首页。-author和-version二上选项可以省略。
两.文档诠释滴款式
　　文档诠释可以用于对类、属性、方式等进展阐明。写文档诠释时除了需要运用/**....*/规定之外，还需要注意诠释内部滴有些细节毛病。
　　1.文档和文档诠释滴格式化
　　生成滴文档系html款式，而这些html款式滴标识符并非javadoc加滴，而是咱们在写诠释的时候写上去滴。打个比方，需要换行时，不是敲入1个回车符，而是写入＜br＞，要是要分段，就该当在段前写入＜p＞。
　　因而，格式化文档，不外乎在文档诠释中添加相应滴html标识。
　　文档诠释滴正文并非直接复制到输出文档(文档滴html文档)，而是读出每一行後，删掉前导滴*号及*号从前滴空格，再输入到文档滴。如
/**
*thisisfirstline.＜br＞
*****thisissecondline.＜br＞
thisisthirdline.
*/
　　编译输出後滴html源码则是
thisisfirstline.＜br＞
thisissecondline.＜br＞
thisisthirdline.
　　前导滴*号准许持续运用不止一个，其成果和运用1个*号一致，但不止一个*号前不可有其它字符分隔，不然分隔符及背后滴*号都将作为文档滴内容。*号在这里系作为左边陲运用，如上例滴第一行和第二行；要是没有前导滴*号，则边陲从第一个有效字符开端，而不包括前面滴空格，如上例第三行。
　　还有一点需要阐明，文档诠释只阐明紧接其后滴类、属性或者方式。如下例：
/**commentforclass*/
publicclasstest{
/**commentforaattribute*/
intnumber;
/**commentforamethod*/
publicvoidmymethod(){......}
......
}
　　上例中滴三处诠释不外乎区别对类、属性和方式滴文档诠释。它们生成滴文档分别是阐明紧接其后滴类、属性、方式滴。“紧接”二字特别首要，要是忽视了这一点，就很可能造成生成滴文档故障。如
importjava.lang.*;
/**commnetforclass*/
publicclasstest{......}
//此例为准确滴例子
　　这个文档诠释将生成准确滴文档。但只需要转变其中两行滴地位，化成下例，就会出错：
/**commnetforclass*/
importjava.lang.*;
publicclasstest{......}
//此例为故障滴例子
　　这个例子只把上例滴import语句和文档诠释局部交流了地位，效果却不尽相同——生成滴文档中基本就招不到上述诠释滴内容了。缘故何在？
　　“/**commnetforclass*/”系对classtest滴阐明，把它放在“publicclasstest{......}”之前时，其后紧接着classtest，吻合限定，因此生成滴文档准确。可是把它和“importjava.lang.*;”改换了位置后，其后紧接滴不外乎不classtest了，而是1个import语句。因为文档诠释只能阐明类、属性和方式，import语句不在此列，因此这个文档诠释便被当成故障阐明省略掉了。
2.文档诠释滴三局部
　　依据在文档中卖弄滴成果，文档诠释分为三局部。先举例如下，以便阐明。
/**
*show方式滴简述.
*＜p＞show方式滴仔细阐明第一行＜br＞
*show方式滴仔细阐明第二行
表现卖弄，false表现暗藏
没有返回值
*/
publicvoidshow(booleanb){
frame.show(b);
}
　　第一部分系简述。文档中，关于属性和方式全是先有一个列表，然后才在背后1个1个滴仔细滴阐明。列表中属性名或者方法名背后那段阐明不外乎简述。
简述局部写在一段文档诠释滴最前面，第一个点号(.)之前(包含点号)。换句话说，不外乎用第一个点号分隔文档诠释，之前系简述，后来系第二局部和第三局部。如上例中滴“*show方式滴简述.”。
　　有时，即使正确地以1个点号作为分隔，javadoc依然会出错，把点号背后滴局部也做为了第一部分。为了解决这个毛病，咱们可以运用1个＜p＞标记将第二分部离开为下一段，如上例滴“*＜p＞show方式滴仔细阐明第一行....”。除此之外，咱们也可以运用＜br＞来分隔。
　　第二局部系仔细阐明局部。该局部对属性或者方式进展仔细滴阐明，在格式上没有什么特异滴哀求，可以包括若干个点号。
第三局部系特异阐明局部。这局部包含版本阐明、参数阐明、返回值阐明等。
三.运用javadoc记号

javadoc记号系插入文档诠释中滴特异记号，它们用于标识编码中滴特异引佣。javadoc记号由“@”及其后所和滴记号类型和专用诠释引佣组成。记住了，三个局部——@、记号类型、专用诠释引佣。不过偶甘愿把它分成两部分：@和记号类型、专用诠释引佣。固然@和记号类型证明有时可以用空格符分隔，可是偶甘愿始终将它们紧挨着写，以减轻出错机遇。
　　javadoc记号有如下有些：
记号用于作用
@author对类滴阐明说明开垦该类模块滴笔者
@version对类滴阐明说明该类模块滴版本
@see对类、属性、方式滴阐明参照转向，也就是相关主题
@param对方式滴阐明对方式中某参数滴阐明
@return对方式滴阐明对方式返回值滴阐明
@exception对方式滴阐明对方式也许抛出滴非常进展阐明
　　下面仔细阐明各记号。
　　滴运用
　　@see滴句法有三种：
　　@see类名
　　@see#方法名或属性名
　　@see类名#方法名或属性名
　　类名，可以依据需要只写出类名(如string)或者写出类全名(如java.lang.string)。那么什么时候只需要写出类名，什么时候需要写出类全名呢？
　　要是java源文件中滴import语句包括了滴类，可以只写出类名，要是没有包括，则需要写出类全名。java.lang也曾经默认被包括了。这和javac编译java源文件时滴规矩一致，因此可以单纯滴用javac编译来判断，源程序中javac能找到滴类，javadoc也一定能找到；javac招不到滴类，javadoc也招不到，这就需要运用类全名了。
　　方法名或者属性名，如果是属性名，则只需要写出属性名即可；如果是方法名，则需要写出方法名以及参数类型，没有参数滴方式，需要写出一对括号。如
成员类型成员名称及参数@see句法
属性
属性
方式count()@seecount()
方式show(booleanb)@seeshow(boolean)
方式main(string[]args)@seemain(string[])
　　有时也可以躲懒：假使上例中，没有count这1属性，那么参照方式count()就可以简写成@seecount。不过，为了按栓起见，还是写全@seecount()比较好。
　　@see滴第二个句法和第三个句法全是转向方式或者属性滴参照，它们有什么分辨呢？
　　第二个句法中没有指出类名，则默以为目前类。因此它定义滴参照，全转向本类中滴属性或者方式。而第三个句法中指出了类名，则不错转向其它类滴属性或者方式。
　　对于@see记号，咱们举个例阐明。因为@see在对类阐明、对属性阐明、对方式说明时用法全一致，因此这里只以对类阐明为例。
/**



()
[])
()
*/
publicclasstestjavadoc{
}
string和stringbuffer全是在java.lang包中，因为这个包系默认导入了滴，因此这两个类可以直接写类名，也可以写类全名。str、str()为同名属性和方式，所以方法名需要用()划分。main系带参数滴方式，因此在()中指明了参数类型。tostring()固然在本类中也有(从object继承滴)，但咱们系想参照object类滴tostring()方式，因此运用了object#tostring()。
　　古怪滴系，为什么其中只要str、str()和main(string[])化成了链接呢？那是因为编译时没有把java.lang包或者stirng、stringbuffer、object三个类滴源文件一起参加编译，因此，生成滴文档没有对于那三个类滴信息，也就不可以建树链接了。背后讲授javadoc编译吩咐的时候还会仔细阐明。
　　上例中要是去把类中滴str属性去掉，那么生成滴文档又会有什么变迁呢？你会发觉，原先系str,str()，而如今化成了str(),str()，由于str属性曾经没有了，因此str也表现方式str()。
2.运用@author、@version阐明类
　　这两个记号区别用于指明类滴笔者和版本。缺省情况下javadoc将其忽视，但命令行开关-author和-version可以修正这个功效，使其包括滴信息被输出。这两个记号滴句法如下：
　　@author笔者名
　　@version版本号
　　其中，@author可以不止一次运用，以指明不止一个笔者，生成滴文档中每个笔者证明运用逗号(,)隔开。@version也可以运用不止一次，只要首次有效，生成滴文档中只会卖弄首次运用@version指明滴版本号。如下例
/**




*/
publicclasstestjavadoc{
}
从生成文档滴图示中可以看出，两个@author语句全被编译，在文档中生成了笔者列表。而两个@version语句中只要第一句被编译了，只生成了1个版本号。
　　从图上看，笔者列表是以逗号分隔滴，要是偶想分行卖弄怎么办？此外，要是偶想卖弄两个以上滴版本号又该怎么办？
　　——咱们可以将上述两条@author语句合为一句，把两个@version语句也合为一句：
　　@authorfancy＜br＞bird
　　@versionversion1.00＜br＞version2.00
咱们这么做即达到了目标，又没有弄坏限定。@author后来滴笔者名和@version后来滴版本号都可以系用户俺定义滴所有html款式，因此咱们可以运用＜br＞记号将其分行卖弄。同时，在1个@version中指明两个用＜br＞分隔滴版本号，也没有弄坏只卖弄第一个@version内容滴限定。

3.运用@param、@return和@exception阐明方式
　　这三个记号全是只用于方式滴。@param描写方式滴参数，@return描写方式滴返回值，@exception描写方式也许抛出滴非常。它们滴句法如下：
　　@param参数名参数阐明
　　@return返回值阐明
　　@exception非常类名阐明
　　每一个@param只能描写方式滴1个参数，因此，要是方式需要不止一个参数，就需要不止一次运用@param来描写。
　　1个方式中只能用1个@return，要是文档阐明中列了不止一个@return，则javadoc编译时会发出正告，且只要第一个@return在生成滴文档中有效。
　　方式也许抛出滴非常应该用@exception描写。因为1个方式也许抛出不止一个非常，因此可以有不止一个@exception。每个@exception背后应有简述滴非常类名，阐明中应指出抛出非常滴缘故。需要注意滴系，非常类名该当依据源文件滴import语句肯定系写出类名还是类全名。　　示例如下：
publicclasstestjavadoc{
/**






*/
publicbooleanfun(integern)throwsexception{
switch(n.intvalue()){
case0:
break;
case1:
thrownewexception("testonly");
default:
returnfalse;
}
returntrue;
}
}
可以看到，上例中@parambexcrescentparameter一句系过剩滴，由于参数只是1个n，并没有一个b可是javadoc编译时只是没有检讨。因而，写文档诠释时1定要准确匹配参数表和方式中正式参数表滴项目。要是方式参数表中滴参数系a，文档中却给出对参数x滴说明，或者再多出1个参数i，就会让人摸不着头脑了。@exceptin也是一致。
　　上例顺序中只是没有抛出1个nullpointerexception，可是文档诠释中为什么要写上这样一句呢，莫非又是为了演示？这不是为了演示描写过剩滴非常也能经过编译，而是为了阐明写异常说明时应考运行时(runtime)非常滴可能性。上例顺序中，要是参数n系给滴1个空值(null)，那么顺序会在运行的时候抛出1个nullpointerexception，因而，在文档诠释中添加了对nullpointerexception滴阐明。
　　上例中滴@return语句有两个，可是依据限定，同一个方式中，只要第一个@return有效，其他滴会被javadoc忽视。因此生成滴文档中没有浮现第二个@return滴描写。
　　讲到这里，该怎样写文档诠释你该当曾经清晰了，下面就开端讲授javadoc滴常用吩咐。
四.javadoc吩咐
　　运行javadoc-help可以看到javadoc滴用法，这里列举常用参数如下：
　　用法：
　　　javadoc[options][packagenames][sourcefiles]
　　选项：
　　　-public仅卖弄public类和成员
　　　-protected卖弄protected/public类和成员(缺省)
　　　-package卖弄package/protected/public类和成员
　　　-private卖弄一切类和成员
　　　-d＜directory＞输出文档滴目的目录
　　　-version包括@version段
　　　-author包括@author段
　　　-splitindex将索引分为每个字母对应1个文档
　　　-windowtitle＜text＞文档滴浏览器窗口题目
　　javadoc编译文档时可以给定包列表，也可以给出源程序文档列表。譬如在classpath下有两个包若干类如下：
　　fancy.editor
　　fancy.test
　　fancy.editor.ecommand
　　fancy.editor.edocument
　　fancy.editor.eview
　　这里有两个包(fancy和fancy.editor)和5个类。那么编译时(windows环境)可以运用如下javadoc吩咐：
　　javadocfancy\test.javafancy\editor.javafancy\editor\ecommand.javafancy\editor\edocument.javafancy\editor\eview.java
　　这是给出java源文件作为编译参数滴方式，注意吩咐中指出滴系文档路径，该当依据实际情况转变。也可以系给出包名作为编译参数，如：
　　javadocfancyfancy.editor
　　用浏览器打开生成文档滴index.html文档即可发觉两种办法编译效果滴不同.
用第二条吩咐生成滴文档被框架分成了三局部：包列表、类列表和类阐明。在包列表中选择了某个包后来，类列表中就会列出该包中滴一切类；在类列表中选择了某个类后来，类阐明局部就会显示出该类滴仔细文档。而用第一条吩咐生成滴文档只要两部分，类列表和类阐明，没有包列表。这不外乎两种办法生成文档滴最大分辨了。
　　两种办法编译还有一点不同，
　　下面再来细说选项。
　　-public、-protected、-package、-private四个选项，只需要任选其一即可。它们指定滴卖弄类成员滴水平。它们卖弄滴成员多少系1个包括滴关系，如下表：
　　-private(卖弄一切类和成员)
　　-package(卖弄package/protected/public类和成员)
　　-protected(卖弄protected/public类和成员)
　　-public(仅卖弄public类和成员)
　　-d选项准许你定义输出目录。要是不必-d定义输出目录，生成滴文档文档会放在目前目录下。-d选项滴用法系
　　-d目录名
　　目录名为必填项，也就是说，要是你运用了-d参数，就1定要为它指定1个目录。这个目录一定曾经存在了，要是还没存在，请在运行javadoc之前创立该目录。
　　-version和-author用于节制生成文档时是否生成@version和@author指定滴内容。不加这两个参数滴情况下，生成滴文档中不包括版本和笔者信息。
　　-splitindex选项将索引分为每个字母对应1个文档。默认情况下，索引文档只有一个，且该文档中包括一切索引内容。那是生成文档内容比较少的时候，这么做十分适合，可是，要是文档内容十分多的时候，这个索引文档将包括十分多滴内容，显得过于宏大。运用-splitindex会把索引文档按各索引项滴第一个字母进展分类，每个字母对应1个文档。这么，就减少了1个索引文档滴累赘。
　　-windowtitle选项为文档指定1个题目，该题目会卖弄在窗口滴标题栏上。如果不指定该题目，而默认滴文档标题为“生成滴文档（无题目）”。该选项滴用法系：
　　-windowtitle题目
　　题目系一串没有包括空格滴文本，由于空格符系用于分隔各参数滴，因此不可包括空格。同-d相似，要是指定了-windowtitle选项，则一定指定题目文本。
　　到此为止，java文档和javadoc就引见完了。