java学习笔记-使用javadoc命令生成API文档

来源：互联网发布：心彻为知的解释编辑：程序博客网时间：2024/04/28 10:50

java中有三种注释：

单行注释、多行注释（和C，C++中的一样）

重点：文档注释

如果编写java源码时添加了文档注释，则可以使用javadoc工具将代码中的文档注释

提取出来做成一份API文档。这样API文档中可以详细列出该类里包含的所有成分。

通过查看该文档，有利于掌握其中类的用法。

在集成开发环境中，可以按照一定的步骤选项进行导出，例如平时使用的

Eclipse，选择Export，选后选择导出javadoc。但是如果学习这个方面的

知识从Eclipse中导出API的方法学起，生活中是有很多集成开发环境的。

那时候如果你换了一个环境后，还要学习那个工具中生成API的方法，这样

是不好的学习方法。所以学习此部分内容还是应该建议使用javadoc命令。

和你使用的编程软件无关。

javadoc命令格式：

javadoc [options] [packagenames] [sourcefiles] [@files]

也就是: javadoc [选项] 文件路径

其选项可以在运行命令提示符，然后输入javadoc 直接回车进行查看。

其常用选项有如下几个：

-d <directory>:该选项指定一个路径，则生成的API文档将被放入指定目录下。

-encoding <name> : 指定源文件的编码类型。

-charset <name>: 指定用于跨平台查看生成的文档的字符集

例如：

该命令将我自己写的一个类生成API，并且存放到E盘的apidoc文件夹下。并且指定其编码和字符集类型都是

utf-8，通常我们不指定的话并且文档注释中存在中文，就会乱码。可以从下图看出，文件创建成功。且成功

生成API.

-windowtitle <text> ：text部分指定一个字符串，用来作为API文档的浏览器窗口的标题。

-doctitle <html-code>: 设置概述界面的标题

-header <html-code>: 包含每个页面的页眉文本

例如：

上面我设置是将自己项目中的所有包都生成API，windowtitle为个人测试，则将来我打开index.html，

网页的标题就会显示个人测试。概述界面标题是我爱学java，页眉文本是我寄几写的类。

-public 仅显示public的类和成员

-protected 显示protected/public 类和成员，而且如果不指定该选项，则默认就是-protected类型，public

和public定义的类和成员可以在API中看到

-private 显示所有类和成员（不管是类和成员是用什么修饰的）

java中方便我们使用的还有javadoc标记，也可以将其生成入API文档。

@author  :指定java程序的作者@version :指定源文件的版本@deprecated :不推荐使用的方法@param : 方法的参数说明信息@return : 方法的返回值说明信息@see : 参见，用来指定交叉参考的内容@exception : 抛出异常的类型@throws : 抛出异常的类型。自己还可以定义一些其他的信息，比如我自己在写文件的时候往往希望留下我编写该代码的时间，所以我自己会加入表示日期的javadoc标记。这些一般在集成开发环境中可以进行自定义的设置。@date 年/月/日@date 2017/12/1

通常这些标记出现的位置也是不同的。

可以出现在类或者接口文档注释中的有@see @deprecated @author @version

可以出现在方法或构造其文档注释中的有@see @deprecated @param @return @throws @exception

可以出现在成员变量的文档注释中的有@see @deprecated

但是当导出API时，这些javadoc注释尽管在源文件中是存在的，但是其并不会出现在API中。

比如author,version等，这时候我们依然需要通过javadoc命令的选项来实现。

-version ：包含@version字段

-author : 包含@author字段

-nodeprecated : 不包含@nodeprecated字段

。。。。。。

例如我希望我的API中包括作者信息和版本信息，我可以写如下指令。