在 IntelliJ IDEA 中为自己设计的类库生成 JavaDoc
因为某个项目需要,为团队其他兄弟姐妹开发了一个 XML 分析处理器,并将其设计为一个类库,提供相应的 API 接口。为了方便大家的使用,需要生成对应的 JavaDoc 帮助文档,就像 JavaSE 标准库提供的 JavaDoc 那样。我的开发工具为 IntelliJ IDEA 12.1.6,本身提供了很好的 JavaDoc 生成功能,以及标准 JavaDoc 注释转换功能,其实质是在代码编写过程中,按照标准 JavaDoc 的注释要求,为需要暴露给使用者的类、方法以及其他成员编写注释。然后使用 IDEA 的功能自动调用 javadoc.exe(JDK 自带的工具)根据源代码中的注释内容自动生成 JavaDoc 文档(超文本格式)。标准 JavaDoc 的注释规则,大家可以在网上很容易搜索到,这里有几点倒是要特别注意一下:
IDEA 的 JavaDoc 生成功能在菜单 Tools->Generate JavaDoc 项里面。
点击上述菜单项后,会出现生成 JavaDoc 的对话框,一般的选项都很直观,不必细说。但是要注意生成 JavaDoc 的源代码对象的选择,一般以模块(Module)为主,必要时可以单独选择必要的 Java 源代码文件,不推荐以 Project 为 JavaDoc 生成的源范围。
里面有一个 Locale 可选填项,表示的是需要生成的 JavaDoc 以何种语言版本展示,根据 javadoc.exe 的帮助说明,这其实对应的就是 javadoc.exe 的 -locale 参数,如果不填,默认可能是英文或者是当前操作系统的语言,既然是国人,建议在此填写 zh_CN,这样生成的 JavaDoc 就是中文版本的,当然指的是 JavaDoc 的框架中各种通用的固定显示区域都是中文的。你自己编写的注释转换的内容还是根据你注释的内容来。
还有一个“Other command line arguments:”可选填项,非常重要,是填写直接向 javadoc.exe 传递的参数内容。因为有一些重要的设置,只能通过直接参数形式向 javadoc.exe 传递。这里必须要填写如下参数:
-encoding UTF-8 -charset UTF-8 -windowtitle "你的文档在浏览器窗口标题栏显示的内容" -link http://docs.oracle.com/javase/7/docs/api
第一个参数 -encoding UTF-8 表示你的源代码(含有符合 JavaDoc 标准的注释)是基于 UTF-8 编码的,以免处理过程中出现中文等非英语字符乱码;第二个参数 -charset UTF-8 表示在处理并生成 JavaDoc 超文本时使用的字符集也是以 UTF-8 为编码,目前所有浏览器都支持 UTF-8,这样最具有通用性,支持中文非常好;第三个参数 -windowtitle 表示生成的 JavaDoc 超文本在浏览器中打开时,浏览器窗口标题栏显示的文字内容;第四个参数 -link 很重要,它表示你生成的 JavaDoc 中涉及到很多对其他外部 Java 类的引用,是使用全限定名称还是带有超链接的短名称,举个例子,我创建了一个方法 public void func(String arg),这个方法在生成 JavaDoc 时如果不指定 -link 参数,则 JavaDoc 中对该方法的表述就会自动变为 public void func(java.lang.String arg),因为 String 这个类对我自己实现的类来讲就是外部引用的类,虽然它是 Java 标准库的类。如果指定了 -link http://docs.oracle.com/javase/7/docs/api 参数,则 javadoc.exe 在生成 JavaDoc 时,会使用 String 这样的短名称而非全限定名称 java.lang.String,同时自动为 String 短名称生成一个超链接,指向官方 JavaSE 标准文档 http://docs.oracle.com/javase/7/docs/api 中对 String 类的详细文档地址。-link 实质上是告诉 javadoc.exe 根据提供的外部引用类的 JavaDoc 地址去找一个叫 package-list 的文本文件,在这个文本文件中包含了所有外部引用类的全限定名称,因此生成的新 JavaDoc 不必使用外部引用类的全限定名,只需要使用短名称,同时可以自动创建指向其外部引用 JavaDoc 中的详细文档超链接。每个 JavaDoc 都会在根目录下有一个 package-list 文件,包括我们自己生成的 JavaDoc。
JavaDoc 生成完毕,即可在其根目录下找到 index.html 文件,打开它就可以看到我们自己的标准 JavaDoc API 文档啦。
在 IntelliJ IDEA 中为自己设计的类库生成 JavaDoc的更多相关文章
- 在IntelliJ IDEA中创建和运行java/scala/spark程序
本文将分两部分来介绍如何在IntelliJ IDEA中运行Java/Scala/Spark程序: 基本概念介绍 在IntelliJ IDEA中创建和运行java/scala/spark程序 基本概念介 ...
- IntelliJ IDEA 中文官方文档
目录 认识IntelliJ IDEA IntelliJ IDEA 安装和设置 IntelliJ IDEA如何使用 IntelliJ IDEA中不容错过的快捷键 IntelliJ IDEA专业的使用技巧 ...
- Intellij Idea中的Jetty报出Web application not found src/main/webapp错误的解决方案
今天在Intellij Idea中编译项目的时候,运行起来一直会报出如下的错误: Web application not found src/main/webapp 当时感觉应该是什么文件缺少了.所以 ...
- Spark Streaming源码解读之Driver中ReceiverTracker架构设计以具体实现彻底研究
本期内容 : ReceiverTracker的架构设计 消息循环系统 ReceiverTracker具体实现 一. ReceiverTracker的架构设计 1. ReceiverTracker可以以 ...
- IntelliJ IDEA中使用综合使用Maven和Struts2
在Intellij IDEA中手动使用Maven创建Web项目并引入Struts2 创建一个新的Maven项目 建好项目之后点击左下角的enable auto import 项目部署 在Moudule ...
- 在Web应用和IntelliJ IDEA中使用Spring框架
在JAVA SE和Web应用中都可以使用Spring, 这里只说在Web程序中的应用. 下面将以Spring 3.0.5版本为例. 在Web中使用Spring只需要如下两个步骤: 第一,将Spring ...
- IntelliJ IDEA 中集成使用git(2015年06月10日)
前提:需要有一个git账号,https://github.com/ 1.首先需要下载一个Github,https://windows.github.com 安装之后的界面是酱紫的,非常简洁美观 2.在 ...
- 看懂此文,不再困惑于 JS 中的事件设计
看懂此文,不再困惑于 JS 中的事件设计 今天刚在关注的微信公众号看到的文章,关于JS事件的,写的很详细也很容易理解,相关的知识点都有总结到,看完就有种很舒畅的感觉,该串起来的知识点都串起来了.反正一 ...
- IntelliJ IDEA中怎样使用JUnit4
背景 近期參与了一个Anroid医疗项目,当中项目底层有非常多基础类及通讯类,并且非常多涉及复杂的字节操作还有多线程同步及状态机处理.这种项目做一下TDD还是必要的,尽量项眼下期把风险减少一些. ...
随机推荐
- 实现类似add(1)(2)(3)的函数
要求实现类似add(1)(2)(3)调用方式的方法,例如add为加法函数,则调用add(1)(2)输出3,调用add(1)(5)(3)输出9. 函数的调用方式是多次调用同一个函数,将每次传入的参数 ...
- js采用正则表达式获取地址栏参数
getQueryString:function(name) { var reg = new RegExp("(^|&)"+ name +"=([^&]*) ...
- House of Spirit(fastbin)
0x01 fastbin fastbin所包含chunk的大小为16 Bytes, 24 Bytes, 32 Bytes, … , 80 Bytes.当分配一块较小的内存(mem<=64 Byt ...
- iOS 常用尺寸
APP ICON: @1x:57*57 @2x:114*114 @3x:171*171 机型 屏幕尺寸 像素(px)pixel 点(pt)point PPI iphone4s 3.5吋 ...
- EAGLView介绍
http://book.51cto.com/art/201108/285446.htm
- nodejs 设置安装包路径的取消和安装cnpm
安装cnpm: $ npm install -g cnpm --registry=https://registry.npm.taobao.org 配置nodejs的npm安装包路径: npm conf ...
- ExtJs如何使用自定义插件动态保存表头配置(隐藏或显示)
关于保存列表表头的配置,一般我们不需要与后台交互,直接保存在 localStorage 中就能满足常规使用需求(需要浏览器支持). 直接上代码,插件: Ext.define('ux.plugin.Co ...
- Java--容器/集合类(Collection)理解和使用
.数组和集合的比较 数组:长度固定,用来存放基本类型的数据 集合:长度不固定,用来存放对象的引用 二.集合类的基本概念 1.java.util包中提供了一些集合类,这些集合类也被称为容器. 常用的集合 ...
- HDU-2544-最短路(floyd)
板子题,实验一下floyd. #include <cstdio> #include <algorithm> #include <cstring> using nam ...
- GIMP暗黑诱惑,部分彩色效果制作
在一些图形处理中经常会用到高逼格的部分彩色,其他部分黑白的效果,今天我就简单记录一下如何操作. 1.选区,先选择要突出的选区,可以用多种方法,钢笔,套绳,小剪刀等等: 2.把选择的区域稍稍调整亮一点: ...