初次使用javadoc

最新推荐文章于 2022-04-07 22:31:31 发布

sharetown

最新推荐文章于 2022-04-07 22:31:31 发布

阅读量322

点赞数

分类专栏： Java

本文链接：https://blog.csdn.net/cyhk24/article/details/104327120

版权

Java 专栏收录该内容

8 篇文章 0 订阅

订阅专栏

文章目录

初次使用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:
*网站：<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

sharetown

关注

0
点赞
踩
0

收藏

觉得还不错? 一键收藏
0
评论
初次使用javadoc

初次使用JavadocJavadoc是Sun公司提供的一个技术，它从程序源代码中抽取类、方法、成员等注释形成一个和源代码配套的API帮助文档。也就是说，只要在编写程序时以一套特定的标签作注释，在程序编写完成后，通过Javadoc就可以同时形成程序的开发文档。其实就是在写java程序的时候按照javadoc支持的格式书写注释，再到命令行窗口执行相关的javadoc代码，最后电脑自动生成HTML格...
复制链接

扫一扫