-------android培训、java培训、期待与您交流! ----------
JDK包含一个很有用的工具,叫做javadoc,它可以由源文件生成一个HTML文档。javadoc实用程序(utility)从下面几个特性中抽取信息:
l 公有类与接口
l 公有的和受保护的方法
l 公有的和受保护的域
每个/**…*/文档注释在标记之后紧跟自由格式文本(free form text)。标记由@开始。如@auther或@param。
自由格式文本的第一句应该是一个概要性的句子。javadoc实用程序自动将这些句子抽取出来形成概要页。
类注释:类注释必须放在import语句之后,类定义之前。
方法注释:每一个方法注释必须放在所描述的方法之前。除了通用标记之外,还可以使用下面的标记:
@param variable description
这个标记将对当前方法的“param”(参数)部分添加一个条目。这个描述可以占据多行,并可以使用HTML标记。一个方法的所有@param标记必须放在一起。
@return description
这个标记将对当前方法添加“return”(返回)部分。这个描述可以跨越多行,并使用HTML标记。
@throws class description
这个标记将添加一个注释,用于表示这个方法有可能抛出异常。
域注释:只需要对公有域(通常指的是静态常量)建立文档。
通用注释:
下面的标记可以用在类文档的注释中:
@auther name
这个标记将产生一个“auther”(作者)条目,可以使用多个@auther标记,每个@auther标记对应一名作者。
@version text
这个标记将产生一个“version”(版本)条目。这里的text可以是对当前版本的任何描述。
下面的标记可以用所有的文档注释:
@since text
这个标记将产生一个“since”(始于)条目。这个的text可以是对引入特性的版本描述@since version 1.7.1
@deprecated text
这个标记将对类、方法或变量添加一个不再使用的注释。text中给出了取代的建议。
@see reference
这个标记将在“see also”部分增加一个超级链接。它可以用于类中,也可以用于方法中。
这里的reference可以选择下列情形之一:
a) package.class#featurelabel
b) <ahref=”…”>label</a>
c) “text”
第一种情况是最常见的,只要提供类、方法或变量的名字,javadoc就在文档中插入一个超链接。列如:
@seecom.horstmann.corejava.Employee#raiseSalary(double)
建立一个链接到com.horstmann.corejava.Employee类的raiseSalary(double)方法的超链接。可以省略包名,甚至把包名和类名都省去,此时,链接将定位于当前包或当前类。
需要注意,一定要使用(#)分隔类名与方法名(或类名与变量名)。
如果@see标记后面有一个双引号(“)字符,文本就会显示在”see also“部分,例如:
@see “Core Java 2 volume 2”
可以为一个特性添加多个@see标记,但必须将它们放在一起。
如果愿意的话,还可以在注释中的任何位置放置指向其他类或方法的超级链接,以及插入一个专用的标记,例如:
{@link package.class#feature label}
这里的特性描述规则与@see标记的规则一样。
包与概述注释
可以直接将类、方法和变量注释放置在Java源文件中,只要用/**…*/文档注释就可以了。但是,要想产生包注释,就需要在每一个包目录中添加一个单独的文件,可以有如下两个选择:
1) 提供一个以package.html命名的HTML文件。在标记<BODY>…</BODY>之间的所有文本都会被抽取出来。
2) 提供一个以package-info.java命名的Java 文件。这个文件必须包含一个初始的以/**和*/界定的Javadoc注释,跟随在一个包语句之后,它不应该包含更多的代码或注释。
还可以为所有的源文件提供一个概述性的注释。这个注释将被放置在一个名为overview.html的文件中,这个文件位于包含源文件的父目录中,标记<BODY>…</BODY>直接的所有文本将被抽取出来。当用户从导航栏中选择“Overview”,就会显示出这些注释的内容。
注释的抽取
1) 这里,假设HTML文件将被存放在目录docDirectory下。执行以下步骤com.horstmann.corejava,就必须切换到包含子目录com的目录。
2) 如果是一个包,应该运行命令:
javadoc –d docDirectorynameofPackage
对于多个包生成文档,运行:
javadoc –d docDirectory nameofPackage1nameofPackage2 …
如果文件在默认包中,运行:
javadoc –d docDirectory *.java
如果省略了-d docDirectory选项,那么HTML文件就会被提取在当前目录下。不建议这么做!!!