初次使用Javadoc
Javadoc是Sun公司提供的一个技术,它从程序源代码中抽取类、方法、成员等注释形成一个和源代码配套的API帮助文档。也就是说,只要在编写程序时以一套特定的标签作注释,在程序编写完成后,通过Javadoc就可以同时形成程序的开发文档。
其实就是在写java程序的时候按照javadoc支持的格式书写注释,再到命令行窗口执行相关的javadoc代码,最后电脑自动生成HTML格式的API文档,文档里的内容就是你之前写的注释内容,只不过在API文档中更加清晰明了地展现出来了。
需要借助命令行窗口(cmd)执行,所以得保证你的java环境配置完成。并不需要格外下载软件之类的
一 、了解javadoc命令的参数
说明:
- -d< directory >: 该选项指定一个路径,用于将生成的API文档放到指定目录下。
- -windowtitle< text >:该选项指定一个字符串,用于设置API文档的浏览器窗口标题。
- -doctitle< html-code >:该选项指定一个HTML格式的文本,用于指定概述页面的标题。(只有对处于多个包下的源文件来生成API文档时,才有概述页面)
- -header< html-code >:该选项指定一个HTML格式的文本,包含每个页面的页眉。
- 除此之外,javadoc命令还包含大量其他选项,大家可通过在命令窗口输入:javadoc -help 获得
以下内容可通过在命令窗口输入:javadoc -help 获得
Tag | 描述 |
---|---|
-overview | 从 HTML 文件读取概览文档 |
-public | 仅显示 public 类和成员 |
-protected | 显示 protected/public 类和成员 (默认值) |
-package | 显示 package/protected/public 类和成员 |
-private | 显示所有类和成员 |
-help | 显示命令行选项并退出 |
-doclet | 通过替代 doclet 生成输出 |
-docletpath
| 指定查找 doclet 类文件的位置 |
-sourcepath | 指定查找源文件的位置 |
-classpath | 指定查找用户类文件的位置 |
-cp | 指定查找用户类文件的位置 |
-exclude | 指定要排除的程序包列表 |
-subpackages | 指定要递归加载的子程序包 |
-breakiterator | 计算带有 BreakIterator 的第一个语句 |
-bootclasspath | 覆盖由引导类加载器所加载的 类文件的位置 |
-source | 提供与指定发行版的源兼容性 |
-extdirs | 覆盖所安装扩展的位置 |
-verbose | 输出有关 Javadoc 正在执行的操作的信息 |
-locale | 要使用的区域设置, 例如 en_US 或 en_US_WIN |
-encoding | 源文件编码名称 |
-quiet | 不显示状态消息 |
-J | 直接将 传递到运行时系统 |
-X | 输出非标准选项的提要 |
通过标准 doclet 提供:
Tag | 描述 |
---|---|
-d | 输出文件的目标目录 |
-use | 创建类和程序包用法页面 |
-version | 包含 @version 段 |
-author | 包含 @author 段 |
-docfilessubdirs | 递归复制文档文件子目录 |
-splitindex | 将索引分为每个字母对应一个文件 |
-windowtitle
| 文档的浏览器窗口标题 |
-doctitle | 包含概览页面的标题 |
-header | 包含每个页面的页眉文本 |
-footer | 包含每个页面的页脚文本 |
-top | 包含每个页面的顶部文本 |
-bottom | 包含每个页面的底部文本 |
-link | 创建指向位于 的 javadoc 输出的链接 |
-linkoffline | 利用位于 的程序包列表链接至位于 的文档 |
-excludedocfilessubdir :… | 排除具有给定名称的所有文档文件子目录。 |
-group :… | 在概览页面中, 将指定的程序包分组 |
-nocomment | 不生成说明和标记, 只生成声明。 |
-nodeprecated | 不包含 @deprecated 信息 |
-noqualifier ::… | 输出中不包括指定限定符的列表。 |
-nosince | 不包含 @since 信息 |
-notimestamp | 不包含隐藏时间戳 |
-nodeprecatedlist | 不生成已过时的列表 |
-notree | 不生成类分层结构 |
-noindex | 不生成索引 |
-nohelp | 不生成帮助链接 |
-nonavbar | 不生成导航栏 |
-serialwarn | 生成有关 @serial 标记的警告 |
-tag ::
| 指定单个参数定制标记 |
-taglet | 要注册的 Taglet 的全限定名称 |
-tagletpath | Taglet 的路径 |
-charset | 用于跨平台查看生成的文档的字符集。 |
-helpfile | 包含帮助链接所链接到的文件 |
-linksource | 以 HTML 格式生成源文件 |
-sourcetab | 指定源中每个制表符占据的空格数 |
-keywords | 使程序包, 类和成员信息附带 HTML 元标记 |
-stylesheetfile
| 用于更改生成文档的样式的文件 |
-docencoding | 指定输出的字符编码 |
二、小试牛刀
先写两个文件来试一下水:
你可以在电脑的任何位置创建两个文件夹
- 例:
- 在E盘下创建两个文件夹,分别是lee和yeelu。
- 在lee文件夹中新建文本文档,然后在文档中输入如下代码:
package lee;
/**
*Description:
*网站:<a herf="http://www.crazyit.org">疯狂java联盟</a><br>
*Copyright (c),2001-2005
*Program Name:<br>
*Date:<br>
*@author:taopoppy.github
*@version:1.0
*/
public class JavadocTest
{
/**
*简单测试成员变量
*/
protected String name;
/**
*主方法,程序的入口
*/
public static void main(String[] args)
{
System.out.println("Hello World");
}
}
- 将文档另存为”JavadocTest.java",文档类型记得改为全部类型,不然你将得到一个名为”JavadocTest.java.txt"的文本文档。
- 再用同样的方法在yeeku文件夹中编写一个Test类,这个类里包含了对象、构造器、成员变量的文档注释。
package yeeku;
/**
*Description:
*网站:<a herf="http://www.crazyit.org">疯狂java联盟</a><br>
*Copyright (c),2001-2005
*Program Name:<br>
*Date:<br>
*@author:taopoppy.github
*@version:1.0
*/
public class Test
{
/**
*简单测试成员变量
*/
public int age;
/**
*Text类的测试构造器
*/
public Test()
{
}
}
- 编写好后同样将文档另存为”Test.java",文档类型记得改为全部类型,不然你将得到一个名为”Test.java.txt"的文本文档。
- 在命令行窗口执行如下命令来为刚刚编写好的两个Java程序生成API文档:
win+r >> cmd >> e: >> cd 到lee文件夹下:
再输入如下代码:(注意:这个代码有可能出现编码方式不可映射错误)javadoc -d apidoc -windowtitle 测试 -doctitle 学习javadocAPI -header 我的类 *JavadocTest.java
(如下图)
如果出现如下错误:
说明是编码方式无法映射,需将上面的代码改为:javadoc -d apidoc -windowtitle 测试 -doctitle 学习javadocAPI -header 我的类 -encoding utf-8 *JavadocTest.java
再次运行将可以正常生成API文档了
此时lee文件夹下将会生成一个名为“apidoc”的文件夹,打开文件夹将会看到一个名为“index.html“的网页文件,打开它
恭喜你你已经成功用javadoc生成了你人生中第一个API文档。 - 快用同样的方法生成”Test.java“的API文档试试。
步骤同上!
代码为:javadoc -d apidoc -windowtitle 测试 -doctitle 学习javadocAPI -header 我的类 *Test.java
三、知识拓展
如果你希望用javadoc工具生成更多详细的文档信息,例如为方法参数、方法返回值等生成详细的说明信息,则可利用javadoc标记。常用的javadoc标记如下:
- @auther: 指定Java程序的作者
- @version: 指定源程序的版本
- @deprecated: 不推荐使用的方法
- @param: 方法的参数说明信息
- @return: 方法的返回值说明信息
- @see: “参见”,用于指定交叉参考的内容
- @exception: 抛出异常的类型
- @throws: 抛出的异常,和@exception同义
需要指出的是,这些标记的使用是有位置限制的。上面这些标记可以出现在类或者接口文档注释中的有@see、@deprecated、@version等;可以出现在方法或者构造器文档注释中的有@see、@deprecated、@param、@return、@exception、@throws等;可以出现在成员变量的文档注释中的有@see、@deprecated等
下面我们来测试以下上面所说的功能:在yeelu文件夹中新建一个“JavadocTagTest.java”文件,代码如下:
package yeeku;
/**
*Description:
*网站:<a herf="http://www.crazyit.org">疯狂java联盟</a><br>
*Copyright (c),2001-2005
*Program Name:<br>
*Date:<br>
*@author:taopoppy.github
*@version:1.0
*/
public class JavadocTagTest
{
/**
*一个得到打招呼字符串的方法
*/
public String hello(String name)
{
return name+"你好!";
}
}
这次为了能提取到文档中的@author和@version等标记信息,在使用javadoc工具时增加-author和-version两个选项,即:
javadoc -d apidoc -windowtitle 测试 -doctitle 学习 javadoc 工具测试 API 文档 -header 我的类 -version -author -encoding utf-8 *Test.java
现在执行对lee包和yeeku包来生成API文档,首先进入lee和yeeku所在路径,执行如下命令:
javadoc -d apidoc -windowtitle 测试 -doctitle 学习 javadoc 工具测试 API 文档 -header 我的类 -version -author -encoding utf-8 lee yeeku
四、用IDEA对一个项目生成Javadoc
1.在工具栏中找到 tools >> Generate JavaDoc…
2.按要求勾选下列参数:
- Whole project>>整个项目都生成
- Custom scope>>自定义范围
- include test source 包含测试目录
- include JDK and … 包含jdk和其他的第三方jari O
- link to JDK documentation…链接到JDK api
- Output directy 生成的文档存放的位置
private、package、protected、public 生成文档的级别(类和方法)
右边的Generate…是选择生成的文档包含的内容,层级树、导航、索引…
再右边是生成的文档包含的内容信息,作者版本等信息 - Locale 语言类型
- Other command line arguments 其他参数
- Maximum heep… 最大堆栈
3.点击OK