您的位置:首页 > 编程语言 > Java开发

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

2017-12-01 17:13 811 查看
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中包括作者信息和版本信息,我可以写如下指令。






从下图中可以看出的确多了作者名称和版本号。






还有很多很多操作,如果有需要,可以在学习。

学了这些命令后,自己能不能做一份平时使用的API,原来对此部分

不了解,之前刚学java,就想不能没有API,要是写的时候方法忘记了,还能

查查文档,就去网上下载了JDK1.8的API,哈哈,真的没有必要下载,其实自己

可以直接用javadoc命令生成就好了,不过做成就是原版的API,没有中文翻译而已,

这不是挺好吗

,还能边看API,边学英文。


学会写出规范、清晰、准确注释是以后工作必备的能力。所以一定要重视。
内容来自用户分享和网络整理,不保证内容的准确性,如有侵权内容,可联系管理员处理 点击这里给我发消息
标签: