javadoc 详解

wking_forever

浏览: 59237 次
性别:
来自: 杭州

最近访客更多访客>>

hongmin118

mpegnet

mysource

273782108

博主相关

博客

微博

相册

留言

关于我

文章分类

全部博客 (63)

社区版块

存档分类

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:\user\src\java\awt\doc-files\中；然后在Button.java文件中加入下面注释

/**

*   This   button   looks   like   this:

*   <img   src= "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:\user\src。那么你可以使用下面的命令：

javadoc   -sourcepath   c:\user\src   com.mypackage

◇   -classpath   classpathlist   指定javadoc查找 "引用类 "的路径。引用类是指带文档的类加上它们引用的任何类。javadoc将搜索指定路径的所有子目录。Classpathlist可以包含多个路径（使用;隔开）。如果省略-classpath，则javadoc使用-sourcepath查找源文件和类文件。举例说明：假定你打算为com.mypackage建立文档，其源文件的位置是C:\user\src，包依赖C:\user\lib中的库。那么你可以使用下面的命令：

javadoc   -classpath   c:\user\lib   -sourcepath   c:\user\src   com.mypackage

◇   -overview   path\filename   告诉javadoc从path\filename所指定的文件中获取概述文档，并且把它放到输出的概述页面（overview-summary.html）中。其中path\filename是相对于-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   path\filename   指定导航条中的help链接所指向的帮助文件。忽略该选项，javadoc将生成缺省的帮助文件。

◇   -stylesheetfile   path\filename   指定javadoc的HTML样式表文件的路径。忽略该选项，javadoc将自动产生一个样式表文件stylesheet.css。

通过上面的介绍，我们了解了javadoc的命令行语法，下面开始介绍javadoc文档注释方法。

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

*我的第一个程序-- <b> Helloworld </b>

*@author   王鸿

*@version   1.0   2001/10/15

*/

public   class   myHelloworld

{

/**

*在main(   )方法中使用的显示用字符串

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

*/

static   String   SDisp

使用下面命令：

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，上面注释所在的文件最后生成的文件是doc\utility\utl.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   packag

分享到：