【Javadoc生成开发文档(Terminal或IDEA中)】

一、Javadoc工具介绍

大家在查看官网文档的时候,会不会感慨人家的帮助文档写的真有逻辑,层次分明?
在这里插入图片描述
不要羡慕,你也可以!Java官方提供了Javadoc工具,便于用户自己生成项目源码配套的API开发文档,供开发人员及其他用户查看使用。该工具通过对源码中定义的类、方法、变量的特定注释信息进行提取,生成对应的开发文档。只要编码人员在源码编写时,进行合法特定的信息注释,在编码结束后即可通过Javadoc工具生成配套的开发文档。
Javadoc工具现在已经不需要单独安装了,在安装JDK的时候已经附带配置好了,大家可去自己的JDK安装路径的bin目录下查看一下,是否存在javadoc.exe,如果存在说明我们可以直接使用,如下所示:
在这里插入图片描述

二、常用标记

上面提到,开发人员需要以特定的注释方式进行注释,Javadoc工具才可以成功生成配套文档,那么下面这些就是所说的特定注释方式,在源码文件中我们需要使用这些标记进行注释,最后才可以被成功识别(切记Java源码中使用文档注释方式):

标签说明
@author 作者作者标识
@version 版本号版本号
@param 参数名描述方法的入参名及描述信息,如入参有特别要求,可在此注释。
@return 描述对函数返回值的注释
@deprecated 过期文本标识随着程序版本的提升,当前API已经过期,仅为了保证兼容性依然存在,以此告之开发者不应再用这个API。
@throws异常类名构造函数或方法所会抛出的异常。
@throws异常类名构造函数或方法所会抛出的异常。
@exception 异常类名同@throws。
@see 引用查看相关内容,如类、方法、变量等。
@since 描述文本API在什么程序的什么版本后开发支持。
{@link包.类#成员 标签}链接到某个特定的成员对应的文档中。
{@value}当对常量进行注释时,如果想将其值包含在文档中,则通过该标签来引用常量的值。

更多可查看官方文档

三、使用方式

javadoc [选项] [java包名] [java源文件名]

其中常用选项如下图所示,大家不用记,需要时直接在本地Terminal中输入

javadoc -help

命令,就会出现如下所示的帮助信息,大家根据需要添加相应的选项即可。

在这里插入图片描述
当然,使用上述命令的前提是大家已经在自己本机中配置好了JDK的环境变量,因为上面提过javadoc.exe文件是在JDK安装目录的bin目录下的,如果没有配置环境变量,这里会提示该命令不存在的错误。

四、生成文档的两种方式

到这里,我已具体实例操作展示两种生成开发文档的过程:
对应文件内容如下:
在这里插入图片描述

1.Terminal方式

Terminal方式其实使用的很少了,毕竟现在各种IDE已经应用的很成熟,很多工作都是一键完成,这里还是简单介绍一下这种方式,大家了解即可:
1)打开本地Terminal(Win+R输入cmd即可):
在这里插入图片描述

2)进入源码对应的包(package):
在这里插入图片描述

3)输入javadoc命令生成开发文档即可(该文档会默认在当前目录下生成):
这里直接生成一个软件包对应的开发文档,也可直接生成单个java源文件的开发文档,此时需要进入到该源文件所在文件目录下。
在这里插入图片描述
生成结果如下:

在这里插入图片描述
使用浏览器打开此处的任意html文件,即可查看本项目对应的开发文档:
在这里插入图片描述

默认只会识别公共类、公共方法对应的注释信息,如果需要调整显示所有类、所有方法可通过第三节中提到的“选项 -private”进行设置。
在这里插入图片描述
4)解决中文乱码问题
此处需特别说明,如果源码中包括中文注释信息,在生成文档中可能会发生中文乱码的现象,我们可通过如下命令去解决,其实还是采用javadoc 命令中的编码选项:

javadoc -encoding UTF-8 -charset UTF-8 [包名] [源文件]

如此,在生成的开发文档中则不会发生乱码现象了:
在这里插入图片描述

2.IDE方式

热门的Java开发IDE当属IDEA,下面介绍一下IDEA中如何生成开发文档:
1)光标选中想要生成对应文档的目录或者文件,然后依次点击Tools->Generate JavaDoc
在这里插入图片描述

打开界面如下所示,在这里可进行开发文档输出目录、注释信息识别范围等选择:
注意此处输出目录建议选择“绝对路径”
在这里插入图片描述

对应生成结果与Terminal方式一样,大家自行测试即可:
在这里插入图片描述

  • 5
    点赞
  • 4
    收藏
    觉得还不错? 一键收藏
  • 打赏
    打赏
  • 2
    评论
评论 2
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包

打赏作者

NorthSmile

你的鼓励将是我创作的最大动力

¥1 ¥2 ¥4 ¥6 ¥10 ¥20
扫码支付:¥1
获取中
扫码支付

您的余额不足,请更换扫码支付或充值

打赏作者

实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值