调用Javadoc程序生成自己项目的API文档

  • Post author:
  • Post category:java


想要生成自己项目的AIP文档,首先你要先给自己的项目添加特殊注释,什么特殊注释呢?在Java中有三种注释,分别是单行注释、多行注释、文档注释。这个特殊注释就是文档注释,添加这个注释是为了能够生成与之对应API文档,你在注释中输入的信息就是生成的API里面的信息。注释写好之后调用Javadoc程序完成代码与文档的分离然后生成API文档。

Javadoc程序有一些生成API文档的相关规则,只有符合这些规则才能生成正确的API文档。文档注释也有一些相关的注释标签,下面是生成API文档的相关规则说明和相关的注释标签:

生成API文档的规则:

  1. Javadoc针对public类生成注释文档
  2. Javadoc只能在public、protected修饰的方法或者属性之上
  3. Javadoc注释的格式化:前导*号和HTML标签
  4. Javadoc注释要仅写在类、属性、方法之前

注释标签:

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

此外还有@serial、@serialField、@serialData、{@docRoot}、{@inheritDoc}、{@literal}、{@code} {@value arg}几个不常用的标签,由于不常使用,我们不展开叙述,有兴趣的可以去查找相关资料。

下面我将我所做的一个简单的例子给大家当做示例了解一下。

上面说了,要将注释写在类、属性、方法之前,如图:在注释中输入类的描述信息,并指明作者(云彩),版本号(1.0);以及方法的描述信息,参数的描述信息,异常的描述信息等相关的信息都可以写。

在这里插入图片描述
在这里插入图片描述

下图是项目的目录结构:

在这里插入图片描述

接下来是调用Javadoc生成项目的API文档的步骤:

第一步:点击MyEclipse的File会弹出如下窗体,然后在点击Export。

在这里插入图片描述

第二步:在弹出的窗体中展开Java文件夹,选中Javadoc然后点击Next。如下图:

在这里插入图片描述

第三步:在弹出的窗体中勾选需要生成API文档的项目,然后点击Browse选择将API文档生成到哪的路径,最后点击Finish。可以看到D:\Java\jdk1.7.0_80\bin\javadoc.exe这样一串路径,这个路径就是JDK中Javadoc程序的路径。

在这里插入图片描述

最后一步:点击Yes To All结束操作,等待API文档生成。

在这里插入图片描述

需要注意的是,如果出现了编码GBK无法映射的字符这样的错误,则不能在第三步点击Finish,需要一直点击Next直到出现下面这个窗体,然后在VM options下输入一句编码转换的代码(-encoding utf-8 -charset utf-8),然后Back上一步回到第三个步骤点击Finish就OK啦。

在这里插入图片描述

接下来我们打开上面输入的API生成路径可以看到生成了下图中的一些文件。

在这里插入图片描述

打开index.html文件看看里面的内容和我们的项目是否对应。

在这里插入图片描述
在这里插入图片描述

根据之前给的项目目录结构,我们知道这个项目有两个包,四个类。在上图中都给我们生成出来了,左上角是所有的包,左下角是所有的类,剩下的是内容,里面关于类、方法等我们在项目中写的注释都生成到这个文档里面了。就这样项目的API文档就算是生成成功了。



版权声明:本文为qq_41708308原创文章,遵循 CC 4.0 BY-SA 版权协议,转载请附上原文出处链接和本声明。