初次使用javadoc

初次使用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:
*网站：疯狂java联盟

*Copyright (c),2001-2005
*Program Name:

*Date:

*@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:
*网站：疯狂java联盟

*Copyright (c),2001-2005
*Program Name:

*Date:

*@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:
*网站：疯狂java联盟

*Copyright (c),2001-2005
*Program Name:

*Date:

*@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.按要求勾选下列参数：

1. Whole project>>整个项目都生成
2. Custom scope>>自定义范围
3. include test source 包含测试目录
4. include JDK and … 包含jdk和其他的第三方jari O
5. link to JDK documentation…链接到JDK api
6. Output directy 生成的文档存放的位置
   private、package、protected、public 生成文档的级别（类和方法）
   右边的Generate…是选择生成的文档包含的内容，层级树、导航、索引…
   再右边是生成的文档包含的内容信息，作者版本等信息
7. Locale 语言类型
8. Other command line arguments 其他参数
9. Maximum heep… 最大堆栈

3.点击OK