快捷搜索:  as  test  1111  test aNd 8=8  test++aNd+8=8  as++aNd+8=8  as aNd 8=8

亚博娱乐国际最新版本:Java平台最“体贴”的工具Javadoc



作者:王鸿本文选自:赛迪网2002年01月28日

在软件项目治理历程中,若何包管法度榜样代码与软件技巧文档同等可以说是最令人头疼的一件工作了。不管是先改动代码,照样先改动文档,对各类记录的治理都是一件麻烦事。而且,二者在篡改上的同等性、实时性还很难获得包管。令人痛快的是Java平台的设计者充分斟酌到了这一点,他们十分"体谅"地为Java开拓者们带来一个文档治理对象--亚博娱乐国际最新版本javadoc。

javadoc使用Java编译法度榜样javac对法度榜样代码源文件中的声明和文档注释进行语法阐发,并在默认环境下天生一组HTML文档来描述类、内部类、接口、构造函数、措施和域。不过在运行历程中,它也应用了Java平台的情况变量classpath来确定类查找路径。这样当涉及类和内部类的有关描述时,是否精确地设置了classpath变量可能会影响到javadoc敕令是否可以完全成功履行。

javadoc孕育发生的默认文件列表如下:

基础页面文件:

calssname.html 类或者接口描述文件,一个文件对应一个类或者接口

package-summary.html 包择要文件,一个文件对应一个包

overview-summary.html 总的择要文件

交叉引用页面文件:

overview-tree.html 所有包的类层次页面

package-tree.html 某个包的类层次页面

package-use.html 包用法页面

class-useclassname.html 类用法页面

deprecated-list.html 不鼓励应用的措施的页面

serialized-form.html 序列化页面

index-*.html 索引文件

支持文件:

help-doc.html 赞助文件

index.html 向导页面,是全部文档的进口

*-frame.html 框架文件

stylesheet.css 样式表文件

doc-files目录 保存与HTML相关的一些杂文件。例如图片文件等。

javadoc的敕令行语法如下:

javadoc [ options ] [ packagenames ] [ sourcefiles ] [ @files ]

参数可以按照随意率性顺序排列。下面分手就这些参数和相关的一些内容进行阐明:

Packagenames 包列表。这个选项可所以一系列的包名(用空格隔开),例如java.lang java.lang.reflect java.awt。不过,由于javadoc不递归感化于子包,不容许对包名应用通配符;以是你必须显示地列出盼望建立文档的每一个包。

Sourcefiles 源文件列表。这个选项可所以一系列的源文件名(用空格隔开),可以应用通配符。javadoc容许四种源文件:类源代码文件、包描述文件、总体概述文件、其他杂文件。

◇ 类源代码文件:类或者接口的源代码文件。

◇ 包描述文件:每一个包都可以有自己的包描述文件。包描述文件的名称必须是"package.html",与包的.java文件放置在一路。包描述文件的内容平日是应用HTML标记写的文档。javadoc履行时将自动探求包描述文件。假如找到,javadoc将首先对描述文件中之间的内容进行处置惩罚,然后把处置惩罚结果放到该包的Package Summary页面中,着末把包描述文件的第一句(紧靠)放到输出的Overview summary页面中,并在语句前面加上该包的包名。

◇ 总体概述文件:javadoc可以创建一个总体概述文件描述全部利用或者所有包。总体概述文件可以被随意率性命名,也可以放置到随意率性位置。-overview选项可以唆使总体概述文件的路径和名称。总体概述文件的内容是应用HTML标记写的文档。javadoc在履行的时刻,假如发明-overview选项,那么它将首先对文件中之间的内容进行处置惩罚;然后把处置惩罚后的结果放到输出的Overview summary 页面的底部;着末把总体概述文件中的第一句放到输出的Overview summary页面的顶部。

◇ 其他杂文件:这些文件平日是指与javadoc输出的HTML文件相关的一些图片文件、Java源代码文件(.java)、Java法度榜样(.class)、Java小法度榜样(Applets)、HTML文件。这些文件必须放在doc-files目录中。每一个包都可以有自己的doc-files目录。举个例子,你盼望在java.awt.Button的HTML文档中应用一幅按钮的图片(Button.gif)。首先,你必须把图片文件放到C:usersrcjavaawtdoc-files中;然后在Button.java文件中加入下面注释

/**

* This button looks like this:

*

*/

@files 包孕文件。为了简化javadoc敕令,你可以把必要建立文档的文件名和包名放在一个或多个文本文件中。例如,为了简化下面敕令:

javadoc -d apidoc com.mypackage1 com.mypackage2 com.mypackage3

你可以建立一个名称为mypackage.txt的文件,其内容如下:

com.mypackage1

com.mypackage2

com.mypackage3

然后履行下面敕令即可:

javadoc -d apidoc @mypackage.txt

options 敕令行选项。javadoc应用doclets(doclets是指用doclet API编写的法度榜样。)来确定输出的内容和款式。敕令行选项中一部分是可用于所有doclet的通用选项,一部分是由默认的标准doclet供给的专用的选项。下面对各自一些常用的选项分手进行先容:

通用选项:

◇ -1.1 天生具有javadoc 1.1版本天生的文档的外不雅和功能的文档。不是所有的选项都可以用于-1.1选项,详细可以应用javadoc -1.1 -help不雅察。

◇ -help 显示联机赞助。

◇ -bootclasspath classpathlis亚博娱乐国际最新版本t 指定"根类"(平日是Java平台自带的一些类。例如java.awt.*等)的路径。

◇ -sourcepath sourcepathlist 指定包的源文件搜索路径。然则必须留意,只有在javadoc敕令中指定了包名的时刻才可以应用-sourcepath选项。假如指定了包名,而省略了-sourcepath,那么javadoc应用类路径查找源文件。举例阐明:假定你盘算为com.mypackage建立文档,其源文件的位置是C:usersrc。那么你可以应用下面的敕令:

javadoc -sourcepath c:usersrc com.mypackage

◇ -classpath classpathlist 指定javadoc查找"引用类"的路径。引用类是指带文档的类加上它们引用的任何类。javadoc将搜索指定路径的所有子目录。Classpathlist可以包孕多个路径(应用;隔开)。假如省略-classpath,则javadoc应用-sourcepath查找源文件和类文件。举例阐明:假定你盘算为com.mypackage建立文档,其源文件的位置是C:usersrc,包依附C:userlib中的库。那么你可以应用下面的敕令:

javadoc -classpath c:userlib -sourcepath c:usersrc com.mypackage

◇ -overview pathfilename 奉告javadoc从pathfilename所指定的文件中获取概述文档,并且把它放到输出的概述页面(overview-summary.html)中。此中pathfilename是相对付-sourcepath的相对路径。

◇ -public 只显示公共类以及成员。

◇ -protected 只显示受保护的和公共的类以及成员。缺省选项。

◇ -package只显示包、受保护的和公共亚博娱乐国际最新版本的类以及成员。

◇ -private 显示所有类和成员。

◇ -doclet class 指定javadoc孕育发生输出内容的自定义doclet类。假如轻忽这个选项,javadoc将应用默认的doclet孕育发生一系列HTML文档。

◇ -docle亚博娱乐国际最新版本tpath classpathlist 与- doclet选项相关,拟订自定义的doclet类文件的路径。Classpathlist可以包孕多条路径(用;隔开)。

◇ -verbose 在javadoc运行时供给更具体的信息。

标准doclet专用选项:

◇ -author 在天生的文档中包孕"作者"项。

◇ - d directory 指定javadoc保存天生的HTML文件的目录。省略该选项将把文件保存在当前目录。Directory可所以绝对目录,也可所以相对当前目录的相对目录。

◇ -version 在天生的文档中包孕"版本"项。

◇ -use 为类和包天生"use"(用法)页面。这些页面描述了该类和包在javadoc敕令涉及的文件中被应用的环境。例如:对付给定的类C,在C的用法页面中将包孕C的子类,类型为C的域,返回变量类型为C的措施以及在参数中有变量类型为C的措施和构造器。

◇ -splitindex 把索引文件按照字母顺序分为多个文件。每一个文件对应一个字母。

◇ -windowtitle title 指定输出的HTML文档的标题。

◇ -header header 指定输出的HTML文档的页眉文本。

◇ -footer footer 指定输出的HTML文档的脚注文本。

◇ -bottom text 指定输出的HTML文档底部的文本。

◇ - group groupheading packagepatten;packagepatten;… 在总体概述页面中按照敕令的指定要领分隔各个包。例如履行下面敕令:

javadoc -group "Core Packages" "java.lang*:java.util"

-group "Extension Packages" "javax.*"

java.lang java.lang.reflect java.util javax.servlet java.new

在页面中将有如下结果:

Core Packages

java.lang

java.lang.reflect

java.util

Extension Packages

javax.servlet

Other Packages

java.new

◇ - noindex 不输出索引文件。

◇ - help 在文件的导航条中轻忽help链接。

◇ - helpfile pathfilename 指定导航条中的help链接所指向的赞助文件。轻忽该选项,javadoc将天生缺省的赞助文件。

◇ -stylesheetfile pathfilename 指定javadoc的HTML样式表文件的路径。轻忽该选项,javadoc将自动孕育发生一个样式表文件stylesheet.css。

经由过程上面的先容,我们懂得了javadoc的敕令行语法,下面开始先容javadoc文档注释措施。

javadoc注释以"/**"开始,以"*/"停止,里面可以包孕通俗文本、HTML标记和javadoc标记。javadoc只处置惩罚源文件中在类/接口定义、措施、域、构造器之前的注释,轻忽位于其他地方的注释。举例如下:

/**

*我的第一个法度榜样--Helloworld

*@author 王鸿

*@version 1.0 2001/10/15

*/

public class myHelloworld

{

/**

*在main( )措施中应用的显示用字符串

*@see #main(java.lang.String[])

*/

static String SDisplay;

/**

*显示HelloWorld

*@param args 从敕令行中带入的字符串

*@return 无

*/

public static void main(String args[])

{

SDisplay = "Hello World " ;

System.out.println( SDisplay );

}

}

应用下面敕令:

javadoc -private -d doc -author -version myHelloworld.java

即可以天生漂亮的关于myHelloworld.java的API文档了。

上面例子中以@开首的标记便是javadoc标记。在Java法度榜样中精确应用javadoc标记是一个优越的注释习气,将异常有助于javadoc自动从源代码文件天生完备的款式化API文档。下面就对各类标记进行具体阐明。

◇ @author name-text 指定天生文档中的"作者"项,从JDK/SDK 1.0开始引入。name-text可以指定多个名字(应用","隔开)。文档注释可以包孕多个类。

◇ {@docroot} 代表孕育发生文档的根路径,从JDK/SDK 1.3开始引入。用法举例如下

/**

*see the copyright

*/

假定天生文档的根目录是doc,上面注释所在的文件着末天生的文件是docutilityutl.html,那么"copyright"的链接会指向..copyright.html。

◇ @deprecated deprecated-text 添加注释,注解不保举应用该API。

◇ @exception class-name description @throw的同义标记,从JDK/SDK 1.0开始引入。

◇ {@link package.class#member label} 插入指向package.class#member的内嵌链接,从JDK/SDK 1.2开始引入。举例阐明,假定注释中有如下文档:

/** Use the {@link #getComponentAt(int, int) getComponentAt} method. */

那么javadoc最毕天生的HTML页面中将有如下内容

Use the getComponentAt method.

◇ @param parameter-name description 描述参数,从JDK/SDK 1.0开始引入。

◇ @return description 描述返回值,从JDK/SDK 1.0开始引入。

◇ @see reference 添加"拜见"标题,此中有指向reference的链接或者文本项,从JDK/SDK 1.0开始引入。@see标记有三种形式,下面分手阐明:

(1)、@see "string" 为"string"添加文本项,不孕育发生链接。

(2)、@see Label 应用HTML标记孕育发生链接

(3)、@see package.class#member Label 应用Java亚博娱乐国际最新版本说话的名字package.class #member孕育发生链接。

◇ @serial field-description 用于缺省可序列化域的注释,从JDK/SDK 1.2开始引入。

◇ @serialField field-name field-type field-description 建立Serializable类的serialPersistentFields成员的ObjectStreamField组件的文档,从JDK/SDK 1.2开始引入。

◇ @serialData data-description data-description建立数据序列和类型的文档,从JDK/SDK 1.2开始引入。

◇ @since since-text 使用since-text内容为文档增添"since"标题,从JDK/SDK 1.1开始引入。

◇ @throws class-name description 与@exception同义。用class-name和description为输出文档添加"抛出"标题,从JDK/SDK 1.2开始引入。

◇ @version version-text 添加"版权"标题,从JDK/SDK 1.0开始引入。

上面先容了标准doclet供给的所有标记。不过,必要留意这些标记的应用是有位置限定的。此中可以呈现在类或者接口文档注释中的标记有:@see、{@link}、@since、@deprecated、@author、@version。可以呈现在措施或者构造器文档注释中的标记有:@see、{@link}、@since、@deprecated、@param、@return、@throws、@exception、@serialData。可以呈现在域文档注释中的有:@see、{@link}、@since、@desprecated、@serial、@serialField。

除了javadoc自身供给的标准标记以外,我们可以定制自己的标记吗?当然可以。只必要对javadoc标准的doclet法度榜样进行扩充即可。实际上,使用javadoc供给的doclet API,不仅可以扩充doclet标记,以致还可以改变javadoc的全部输出。为了满意必要,你可以使javadoc输出通俗文本、XML文件等。因为扩充doclet涉及到Java编程,本文不再做深入先容。

总之,javadoc供给了完备规范的API文档功能。在软件项目治理中,合理地应用javadoc不仅可以削减开拓时的文档事情量,前进效率;而且还异常有利于将来软件的改动和掩护。

免责声明:以上内容源自网络,版权归原作者所有,如有侵犯您的原创版权请告知,我们将尽快删除相关内容。

您可能还会对下面的文章感兴趣: