Java文档注解

JDK的bin目录下你可以找到javadoc(如果是Windows下的JDK,它的文件名为javadoc.exe).使用javdoc编译.java源文件时,它会读出.java源文件中的文档注释,并按照一定的规则与Java源程序一起进行编译,生成文档.

javadoc -d 文档存放目录 -author -version 源文件名.java
这条命令编译一个名为"源文件名.java"的java源文件,并将生成的文档存放在"文档存放目录"指定的目录下,生成的文档中index.html就是文档的首页.(-author和-version两个选项可以省略).

生成的文档是HTML格式,而这些HTML格式的标识符并不是javadoc加的,而是我们在写注释的时候写上去的.比如,需要换行时,不是敲入一个回车符,而是写入<br>,如果要分段,就应该在段前写入<p>.
因此,格式化文档,就是在文档注释中添加相应的HTML标识.

文档注释只能说明类,属性和方法.

文档注释的正文并不是直接复制到输出文件(文档的HTML文件),而是读取每一行后,删掉前导的*号及*号以前的空格,再输入到文档的.如
/**
*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.

允许连续使用多个*,效果和一个*一样,但多个*号前不能有其它字符分隔,否则分隔符及后面的*号都将作为文档的内容.

*号在这里作为左边界使用,如果没有前导的*号,则边界从第一个有效字符开始,而不包括前面的空格,如上例第三行.

文档注释只说明紧接其后的类,属性或者方法.

文档注释分为三部分:
/**
* show方法的简述.
* <p>show 方法的详细说明第一行<br>
* show 方法的详细说明第二行
* @param b true表示显示,false表示隐藏* @return没有返回值
*/
public void show(boolean b){frame.show(b);}

javadoc标记由"@"及其后所跟的标记类型和专用注释引用组成.
标记                   用于                      作用
@author             对类的说明           标明开发该类模块的作者
@version            对类的说明             标明该类模块的版本
@see           对类,属性,方法的说明   参考转向,也就是相关主题
@param            对方法的说明           对方法中某参数的说明
@return           对方法的说明            对方法返回值的说明
@exception        对方法的说明        对方法可能抛出的异常进行说明

1.@see的使用
@see的句法有三种:
@see类名
@see#方法名或属性名
@see类名#方法名或属性名

如果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[])

没有指出类名,则默认为当前类.所以它定义的参考,都转向本类中的属性或者方法.而第三个句法中指出了类名,则还可以转向其它类的属性或者方法.

关于@see标记,我们举个例说明.由于@see在对类说明,对属性说明,对方法说明时用法都一样,所以这里只以对类说明为例.
/**
* @see String
* @see java.lang.StringBuffer
* @see #str
* @see #str()
* @see #main(String[])
* @see Object#toString()*/
public class TestJavaDoc{}
String和StringBuffer都是在java.lang包中,由于这个包是默认导入了的,所以这两个类可以直接写类名,也可以写类全名.str,str()为同名属性和方法,所以方法名需要用()区分.main是带参数的方法,所以在()中指明了参数类型.toString()虽然在本类中也有(从Object继承的),但我们是想参考Object类的toString()方法,所以使用了Object#toString().

为什么其中只有str,str()和main(String[])变成了链接呢?
那是因为编译时没有把java.lang包或者Stirng,StringBuffer,Object三个类的源文件一起加入编译,所以,生成的文档没有关于那三个类的信息,也就不可以建立链接了.

上例中如果去把类中的str属性去掉,那么生成的文档又会有什么变化呢?

你会发现,原来是str,str(),而现在变成了str(),str(),因为str属性已经没有了,所以str也表示方法str().

2.使用@author,@version说明类

这两个标记分别用于指明类的作者和版本.缺省情况下javadoc将其忽略,但命令行开关-author和-version可以修改这个功能,使其包含的信息被输出.这两个标记的句法如下:
@author 作者名
@version 版本号
@author可以多次使用,以指明多个作者,生成的文档中每个作者之间使用逗号(,)隔开.
@version也可以使用多次,只有第一次有效,生成的文档中只会显示第一次使用@version指明的版本号.

/**
* @author Fancy
* @author Bird
* @version Version 1.00
* @version Version 2.00
*/
public class TestJavaDoc{}
可以将上述两条@author语句合为一句,把两个@version语句也合为一句:
@author Fancy<br>Bird
@version Version 1.00<br>Version 2.00

使用@param,@return和@exception说明方法
这三个标记都是只用于方法的.
@param描述方法的参数
@return 描述方法的返回值
@exception 描述方法可能抛出的异常.

@param 参数名 参数说明
@return 返回值说明
@exception 异常类名 说明

每一个@param只能描述方法的一个参数,所以,如果方法需要多个参数,就需要多次使用@param来描述.

一个方法中只能用一个@return,如果文档说明中列了多个@return,则javadoc编译时会发出警告,且只有第一个@return在生成的文档中有效.

方法可能抛出的异常应当用@exception描述.由于一个方法可能抛出多个异常,所以可以有多个@exception.每个@exception后面应有简述的异常类名,说明中应指出抛出异常的原因.需要注意的是,异常类名应该根据源文件的import语句确定是写出类名还是类全名.

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 -help可以看到javadoc的用法,这里列举常用参数如下:
用法:javadoc [options] [packagenames] [sourcefiles]
选项:
-public 仅显示 public 类和成员
-protected 显示 protected/public 类和成员 (缺省)
-package 显示 package/protected/public 类和成员
-private 显示所有类和成员
-d <directory> 输出文件的目标目录
-version 包含 @version 段
-author 包含 @author 段
-splitindex 将索引分为每个字母对应一个文件
-windowtitle <text> 文档的浏览器窗口标题

Javadoc编译文档时可以给定包列表,也可以给出源程序文件列表.例如在 CLASSPATH 下有两个包若干类如下:
fancy.Editor
fancy.Test
fancy.editor.ECommand
fancy.editor.EDocument
fancy.editor.EView

这里有两个包(fancy和fancy.editor)和5个类.那么编译时(Windows环境)可以使用如下javadoc命令:
javadoc fancy\Test.java fancy\Editor.java fancy\editor\ECommand.java fancy\editor\EDocument.java fancy\editor\EView.java
这是给出java源文件作为编译参数的方法,注意命令中指出的是文件路径,应该根据实际情况改变.也可以是给出包名作为编译参数,如:
javadoc fancy fancy.editor
用浏览器打开生成文档的index.html文件即可发现两种方式编译结果的不同.

用第二条命令生成的文档被框架分成了三部分:包列表,类列表和类说明.在包列表中选择了某个包之后,类列表中就会列出该包中的所有类.在类列表中选择了某个类之后,类说明部分就会显示出该类的详细文档.而用第一条命令生成的文档只有两部分,类列表和类说明,没有包列表.

-public
-protected
-package
-private
四个选项,只需要任选其一即可.它们指定的显示类成员的程度.它们显示的成员多少是一个包含的关系,如下表:
-private (显示所有类和成员)
-package (显示 package/protected/public 类和成员)
-protected (显示 protected/public 类和成员)
-public (仅显示 public 类和成员)
-d 选项允许你定义输出目录.如果不用 -d 定义输出目录,生成的文档文件会放在当前目录下.-d 选项的用法是
-d 目录名

目录名为必填项,也就是说,如果你使用了-d参数,就一定要为它指定一个目录.这个目录必须已经存在了,如果还不存在,请在运行javadoc之前创建该目录.
-version和-author用于控制生成文档时是否生成@version和@author指定的内容.不加这两个参数的情况下,生成的文档中不包含版本和作者信息.

-splitindex选项将索引分为每个字母对应一个文件.默认情况下,索引文件只有一个,且该文件中包含所有索引内容.当然生成文档内容不多的时候,这样做非常合适,但是,如果文档内容非常多的时候,这个索引文件将包含非常多的内容,显得过于庞大.使用 -splitindex 会把索引文件按各索引项的第一个字母进行分类,每个字母对应一个文件.这样,就减轻了一个索引文件的负担.

-windowtitle选项为文档指定一个标题,该标题会显示在窗口的标题栏上.如果不指定该标题,而默认的文档标题为"生成的文档（无标题）".
-windowtitle标题
标题是一串没有包含空格的文本,因为空格符是用于分隔各参数的,所以不能包含空格.同-d类似,如果指定了-windowtitle选项,则必须指定标题文本.