一 申明
以下内容 sort by mang
二 javadoc 简介
我们知道Java中有三种注释语句：
1.//用于单行注释。
成Html格式的类说明文档。javadoc不但能对一个 java源文件生成注释文档，而且能对目录和包生成交叉链接的 html格式的类说明文档，十分方便。
注释中可以出现的关键字，以@开头：
@author 作者名
三 例子：
以下是一个关于汽车类的例子，来具体说明运用javadoc 命令时对注释的规范
汽车类有4个属性：
maxSpeed
averageSpeed
waterTemperature
Temperature
分别用来表示最大速度，平均速度，水温 室温
有2个方法：
measureMaxSpeed()
用来测量汽车的平均速度和最大速度
以下例子基本包括了javadoc 中常用到的注释，下面的篇幅中会一一详细说明的，读者可以试着用javadoc命令生成以下例子的说明文档
/**
*汽车类的简介
*<p>汽车类具体阐述第一行<br>
*汽车类具体阐述第二行
*@author man
*@author man2
*@version 1.0
*@see ship
*@see aircraft
*/
public class Bus{
/**
*用来标识汽车行驶当中最大速度
*@see #averageSpeed
*/
public int maxSpeed;
/**用来标识汽车行驶当中平均速度*/
public int averageSpeed;
/**用来标识汽车行驶当中的水温*/
public int waterTemperature;
/**用来标识天气温度*/
public int Temperature;
Bus(){
}
/**
*该方法用来测量一段时间内的平均速度
*@param start 起始时间
*@param end 截止时间
*@return 返回int型变量
*@exception java.lang.exceptionthrowwhenswitchis1
*/
public int measureAverageSpeed(int start,int end ){
int aspeed=12;
return aspeed;
}
/**
*该方法用来测量最大速度
*/
public int measureMaxSpeed(){
}
}四 javadoc 命令对注释规范的详细介绍 只有/**……*/这样的诠释才能被写入javadoc文档。
4.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二上选项可以省略。
4.2 文档诠释的款式
文档诠释可以用于对类、属性、方式等进行阐明。写文档诠释时除了需要运用/**....*/规定之外，还需要注意
诠释内部的有些细节毛病。
4.2.1文档和文档诠释的格式化
生成的文档系html款式，而这些html款式的标识符并非javadoc加的，而是咱们在写诠释的时候写上去的。
打个比方，需要换行时，不是敲入1个回车符，而是写入＜br＞，要是要分段，就该当在段前写入＜p＞。 因
而，格式化文档，不外乎在文档诠释中添加相应的html标签。
文档诠释的正文并非直接复制到输出文档(文档的html文档)，而是读出每一行后，删掉前导的*号及*号从前
的空格，再输入到文档的。如
/** *thisisfirstline.＜br＞
编译输出后的html源码则是
thisisfirstline.
＜br＞
＜br＞
thisisthirdline.
前导的*号准许持续运用不止一个，其成果和运用1个*号一致，但不止一个*号前不可有其它字符分隔，不然
分隔符及背后的*号都将作为文档的内容。*号在这里系作为左边界运用，如上例的第一行和第二行；要是没有前
导的*号，则边界从第一个有效字符开端，而不包括前面的空格，如上例第四行。
还有一点需要阐明，文档诠释只阐明紧接其后的类、属性或者方式。如下例：
/**comment for a attribute*/
public void mymethod(){......} ...... }上例中的三处诠释不外乎区别对类、属性和方法的文档诠释。它们生成的文档分别是阐明紧接其后的类
、属性、方法的。“紧接”二字特别首要，要是忽视了这一点，就很可能造成生成的文档故障。如
import java.lang.*;
public class Test{......} //此例为准确的例子这个文档诠释将生成准确的文档。但只需要转变其中两行的位置，化成下例，就会出错：
/**comment for class*/
public class Test{......} //此例为故障的例子不到上述诠释的内容了。缘故何在？ “/**comment for class*/”系对 Test类的阐明，把它放在“public class
换了位置后，其后紧接的不再是类Test了，而是一个import语句。因为文档诠释只能阐明类、属性和方式，
import语句不在此列，因此这个文档诠释便被当成故障阐明省略掉了。
4.2.2 文档诠释的三局部
依据在文档中的成果，文档诠释分为三局部。先举例如下，以便阐明。
*汽车类的简述.
*<p>汽车类具体阐述第一行<br>
*汽车类具体阐述第二行
*@author man
*@author man2
*@version 1.0
*@see ship
*@see aircraft
*/
public class Bus{
//类中的语句…………
}
第一部分系简述，也就是注释中的的第二行。文档中，关于属性和方式全是先有一个列表，然后才在背后 一个一个的仔细的阐明。列表中属性名或者方
法名背后那段阐明不外乎简述。 简述局部写在一段文档诠释的最前面，第一个点号(.)之前(包含点号)。换句话
说，不外乎用第一个点号分隔文档诠释，之前系简述，后来系第二局部和第三局部。如上例中的“*汽车类的简
述.”。 有时，即使正确地以1个点号作为分隔，javadoc依然会出错，把点号背后的局部也做为了第一部分。为
了解决这个毛病，咱们可以运用一个＜p＞标记将第二部分离开为下一段，如上例的“*＜p＞show方式的仔细阐
明第一行....”。除此之外，咱们也可以运用＜br＞来分隔。 第二局部系仔细阐明局部。该局部对属性或者方式进
行仔细的阐明，在格式上没有什么特异的哀求。第三局部系特异阐明局部。这局部包含版本阐明、参数阐明、返
回值阐明等。
4.2.3运用javadoc记号
javadoc记号系插入文档诠释中的特异记号，它们用于标识编码中的特异引佣。javadoc记号由“@”及其后所
跟的记号类型和专用诠释引佣组成。记住了，三个局部——@、记号类型、专用诠释引佣。不过我甘愿把它分成
两部分：@和记号类型、专用诠释引佣。 注意 @和记号类型最好紧挨着一块写
javadoc记号有如下这些：
@author 对类的阐明 说明开发该类模块的笔者
@version 对类的阐明 说明该类模块的版本
@see 对类、属性、方式的阐明 参照转向，也就是相关主题
@param 对方式的阐明
@return 对方式的阐明 对方式返回值的阐明
@exception 对方式的阐明 对方式也许抛出的非常进展阐明
下面仔细阐明各记号。
4.2.3.1
@see的句法有三种：
@see 类名
@see #方法名或属性名
@see 类名#方法名或属性名
注意see后面有空格 类名，可以依据需要只写出类名(如string)或者写出类全名(如java.lang.string)。那么什么时
候只需要写出类名，什么时候需要写出类全名呢？ 要是java源文件中的import语句包括了的类，可以只写出类
名，要是没有包括，则需要写出类全名。java.lang也曾经默认被包括了。这和javac编译java源文件时的规矩一
致，因此可以单纯的用javac编译来判断，源程序中javac能找到的类，javadoc也一定能找到；javac找不到的
类，javadoc也招不到，这就需要运用类全名了。 方法名或者属性名，如果是属性名，则只需要写出属性名即
可；如果是方法名，则需要写出方法名以及参数类型，没有参数的方式，需要写出一对括号。如 成员类型 成员
名称 及参数 @see句法 属性number：@see number 属性count：@see count 方式count()：@see count() 方式
show(boolean b)：@see show(boolean) 方式main(string[]args)：@see main(string[]) 有时也可以躲懒：假使上
例中，没有count这1属性，那么参照方式count()就可以简写成@see count。不过，为了安全起见，还是写全
@see count()比较好。 @see的第二个句法和第三个句法全是转向方式或者属性的参照，它们有什么分辨呢？ 第
二个句法中没有指出类名，则默以为目前类。因此它定义的参照，全转向本类中的属性或者方式。而第三个句法
中指出了类名，则不错转向其它类的属性或者方式。 对于@see记号，咱们举个例阐明。因为@see在对类阐
明、对属性阐明、对方式说明时用法全一致，因此这里只以对类阐明为例。
/**
*@see string
*@see java.lang.stringbuffer
*@see #str
*@see #str()
*@see #main(String[])
*@see object#tostring()
*/
public class TestJavadoc{
public int str;
public void str(){
//…………
}
public static void main(String args[]){
//…………
}
}
string和stringbuffer全是在java.lang包中，因为这个包系默认导入了的，因此这两个类可以直接写类名，也可以
写类全名。str、str()为同名属性和方式，所以方法名需要用()划分。main系带参数的方式，因此在()中指明了参
数类型，注意main函数中的参数String是大写，若写错或写成小写则不能生成链接。tostring()固然在本类中也有
(从object继承的)，但咱们系想参照object类的tostring()方式，因此运用了object#tostring()。 古怪的是，为什么
其中只有str、str()和main(string[])化成了链接呢？那是因为编译时没有把java.lang包或者stirng、stringbuffer、
object三个类的源文件一起参加编译，因此，生成的文档没有对于那三个类的信息，也就不可以建立链接了。背
后讲授javadoc编译命令的时候还会仔细阐明。 上例中要是把类中的str属性去掉，那么生成的文档又会有什么变
迁呢？你会发觉，原先系str,str()，而如今化成了str(),str()，由于str属性已经没有了，因此str也表现方法str()。
4.2.3.2 运用@author、@version阐明类
这两个记号区别用于指明类的笔者和版本。缺省情况下javadoc将其忽视，但命令行开关-author和-version
可以修正这个功效，使其包括的信息被输出，即在使用javadoc 命令时加上相关参数,如：
javadoc –d [存放路径] –author –version 类名.java
这两个记号的句法如下： @author笔者名 @version版本号 其中，@author可以不止一次运用，以指明不止一个笔者，生成的文档中每个笔者证明运用逗号(,)隔开。@version也可以运用不止一次，但只有首次有效，生成的文档中只会显示首次运用@version指明的版本号。如下例
/** *@author fancy
*@author bird
*@version version1.00
*@version version2.00 */
public class TestJavadoc{ }从生成文档的图示中可以看出，两个@author语句全被编译，在文档中生成了笔者列表。而两个@version语句中
只要第一句被编译了，只生成了1个版本号。 从图上看，笔者列表是以逗号分隔的，要是偶想分行卖弄怎么办？
此外，要是偶想卖弄两个以上的版本号又该怎么办？ ——咱们可以将上述两条@author语句合为一句，把两个
@version语句也合为一句：
@authorfancy＜br＞bird
@versionversion1.00＜br＞version2.00
咱们这么做即达到了目标，又没有弄坏限定。
@author后来的笔者名和@version后来的版本号都可以系用户俺定义的所有html款式，因此咱们可以运用＜br＞
记号将其分行卖弄。同时，在1个@version中指明两个用＜br＞分隔的版本号，也没有弄坏只卖弄第一个
@version内容的限定。
4.2.3.3 运用@param、@return和@exception阐明方式
这三个记号全是只用于方法的。
@param描写方式的参数，
@return描写方式的返回值，
@exception描写方式也许抛出的异常。
它们的句法如下：
@param参数名参数阐明
@return返回值阐明
@exception异常类名阐明
每一个@param只能描写方式的1个参数，因此，要是方式需要不止一个参数，就需要不止一次运用
@param来描写。 1个方式中只能用1个@return，要是文档阐明中列了不止一个@return，则javadoc编译时
会发出正告，且只要第一个@return在生成的文档中有效。 方法也许抛出的异常应该用@exception描写。
因为一个方式也许抛出不止一个非常，因此可以有不止一个@exception。每个@exception背后应有简述的
异常类名，阐明中应指出抛出异常的缘故。需要注意的系，异常类名该当依据源文件的import语句肯定系写
出类名还是类全名。 示例如下：
public class TestJavadoc{
/** *@param n a switch
*@param b excrescent parameter
*@return true o rfalse
*@return excrescent return
*@exception java.lang.exceptionthrowwhenswitchis1
*@exception nullpointerexception throw when parametern is null */
public Boolean fun(integer n)throws exception{
switch(n.intvalue()){
case0: break;
case1: throw newexception("testonly");
default: return false;
}
return true;
}可以看到，上例中@param bexcrescentparameter一句系过剩的，由于参数只是1个n，并没有一个b可是
javadoc编译时只是没有检讨。因而，写文档诠释时一定要准确匹配参数表和方式中正式参数表的项目。要是方
式参数表中的参数系a，文档中却给出对参数x的说明，或者再多出1个参数i，就会让人摸不着头脑了。
@exceptin也是一致。 上例顺序中只是没有抛出1个nullpointerexception，可是文档诠释中为什么要写上这样一
句呢，莫非又是为了演示？这不是为了演示描写过剩的非常也能经过编译，而是为了阐明写异常说明时应考运行
时(runtime)非常的可能性。上例顺序中，要是参数n系给的1个空值(null)，那么顺序会在运行的时候抛出1个
nullpointerexception，因而，在文档诠释中添加了对nullpointerexception的阐明。 上例中的@return语句有两
个，可是依据限定，同一个方法中，只要第一个@return有效，其他的会被javadoc忽视。因此生成的文档中没有
浮现第二个@return的描写。 讲到这里，该怎样写文档诠释你该当曾经清晰了，下面就开端讲授javadoc的常用
命令。
以下几点还须再次注意
1)
在对属性，方法进行说明时要加上属性或方法的权限，否则在生成的文档中根本找不到该属性或方法
2)
#是针对方法或属性，换句话说要see方法名或属性名 时才用到#
对#的要求:
