分享
 
 
 

JavaDoc命令使用说明

王朝java/jsp·作者佚名  2008-05-31
窄屏简体版  字體: |||超大  

Javadoc的命令行语法如下:

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

参数可以按照任意顺序排列。下面分别就这些参数和相关的一些内容进行说明:

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

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

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

◇ 包描述文件:每一个包都可以有自己的包描述文件。包描述文件的名称必须是"package.Html",与包的.java文件放置在一起。包描述文件的内容通常是使用HTML标记写的文档。javadoc执行时将自动寻找包描述文件。假如找到,javadoc将首先对描述文件中<body></body>之间的内容进行处理,然后把处理结果放到该包的Package Summary页面中,最后把包描述文件的第一句(紧靠<body>)放到输出的Overview summary页面中,并在语句前面加上该包的包名。

◇ 总体概述文件:javadoc可以创建一个总体概述文件描述整个应用或者所有包。总体概述文件可以被任意命名,也可以放置到任意位置。-overview选项可以指示总体概述文件的路径和名称。总体概述文件的内容是使用HTML标记写的文档。javadoc在执行的时候,假如发现-overview选项,那么它将首先对文件中<body></body>之间的内容进行处理;然后把处理后的结果放到输出的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:

* <img src="http://www.QQread.com/java/doc-files/Button.gif">

*/

•@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 classpathlist 指定"根类"(通常是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文档。

◇ -docletpath 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注释以"/**"开始,以"*/"结束,里面可以包含普通文本、HTML标记和javadoc标记。javadoc只处理源文件中在类/接口定义、方法、域、构造器之前的注释,忽略位于其他地方的注释。举例如下:

/**

*Demo--<b>Helloworld</b>

*@author sunjl

*@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 <a href={@docroot}/copyright.html>copyright</a>

*/

假定生成文档的根目录是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 <a href = "Component.html#getComponentAt(int,int)" > getComponentAt </a> 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 <a href="URL#Value">Label</a> 使用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不仅可以减少开发时的文档工作量,提高效率;而且还非常有利于将来软件的修改和维护。

JavaDoc 书写规范:

1、File Header Comments : 每个文件都应该加上文件头标记,包括文件名、修改历史、版权信息和附加信息。例如:

/**

* @(#)demo.java 1.00 2002/05/27

*

* Copyright (c) 2000-2002 中国平安保险股份有限公司 版权所有

* Ping An Insurance Company of China. All rights reserved.

* This software is the confidential and proprietary

* information of Ping An Insurance Company of China.

* ("Confidential Information"). You shall not disclose

* sUCh Confidential Information and shall use it only

* in accordance with the terms of the contract agreement

* you entered into with Ping An.

*/

2、class description:类信息,概括的描述类的功能和实现。

/** class description

*/

3、Variable Description:描述变量的意义和取值含义。

/** var variable description

*/

4、Method Description:标明每个方法的输入、输出参数和返回值类型,说明非凡变量取值的含义。相关类文档链接。

/** method description

* @param var signification

* @exception exception class name

* @return return_value return signification

*/

5、Association Description:关联类文档描述,在注释当中需要参引其它文档描述的地方,可在相应的注释当中如下插入:

/** method description

* @param var signification

* @exception exception class name

* @return return_value return signification

* @see package.class#memberlabel

*/

6、包描述文件:概括描述包的功能和设计概要。为每个包创建一个描述文件,命名为package.html,与包的java文件放在一起。

注:javadoc生成文档时,会将该html文件的第一句放在package summary中,而把整个内容放在Overview summary中.

 
 
 
免责声明:本文为网络用户发布,其观点仅代表作者个人观点,与本站无关,本站仅提供信息存储服务。文中陈述内容未经本站证实,其真实性、完整性、及时性本站不作任何保证或承诺,请读者仅作参考,并请自行核实相关内容。
2023年上半年GDP全球前十五强
 百态   2023-10-24
美众议院议长启动对拜登的弹劾调查
 百态   2023-09-13
上海、济南、武汉等多地出现不明坠落物
 探索   2023-09-06
印度或要将国名改为“巴拉特”
 百态   2023-09-06
男子为女友送行,买票不登机被捕
 百态   2023-08-20
手机地震预警功能怎么开?
 干货   2023-08-06
女子4年卖2套房花700多万做美容:不但没变美脸,面部还出现变形
 百态   2023-08-04
住户一楼被水淹 还冲来8头猪
 百态   2023-07-31
女子体内爬出大量瓜子状活虫
 百态   2023-07-25
地球连续35年收到神秘规律性信号,网友:不要回答!
 探索   2023-07-21
全球镓价格本周大涨27%
 探索   2023-07-09
钱都流向了那些不缺钱的人,苦都留给了能吃苦的人
 探索   2023-07-02
倩女手游刀客魅者强控制(强混乱强眩晕强睡眠)和对应控制抗性的关系
 百态   2020-08-20
美国5月9日最新疫情:美国确诊人数突破131万
 百态   2020-05-09
荷兰政府宣布将集体辞职
 干货   2020-04-30
倩女幽魂手游师徒任务情义春秋猜成语答案逍遥观:鹏程万里
 干货   2019-11-12
倩女幽魂手游师徒任务情义春秋猜成语答案神机营:射石饮羽
 干货   2019-11-12
倩女幽魂手游师徒任务情义春秋猜成语答案昆仑山:拔刀相助
 干货   2019-11-12
倩女幽魂手游师徒任务情义春秋猜成语答案天工阁:鬼斧神工
 干货   2019-11-12
倩女幽魂手游师徒任务情义春秋猜成语答案丝路古道:单枪匹马
 干货   2019-11-12
倩女幽魂手游师徒任务情义春秋猜成语答案镇郊荒野:与虎谋皮
 干货   2019-11-12
倩女幽魂手游师徒任务情义春秋猜成语答案镇郊荒野:李代桃僵
 干货   2019-11-12
倩女幽魂手游师徒任务情义春秋猜成语答案镇郊荒野:指鹿为马
 干货   2019-11-12
倩女幽魂手游师徒任务情义春秋猜成语答案金陵:小鸟依人
 干货   2019-11-12
倩女幽魂手游师徒任务情义春秋猜成语答案金陵:千金买邻
 干货   2019-11-12
 
推荐阅读
 
 
 
>>返回首頁<<
 
靜靜地坐在廢墟上,四周的荒凉一望無際,忽然覺得,淒涼也很美
© 2005- 王朝網路 版權所有