IDEA使用——生成超文本格式的（HTML）JavaDoc

概述

在大型项目中不免会有很多对外暴露的方法与接口，那我们就需要在类或者方法上面按照JavaDoc标准编写注释，就比如这样：

前面我们也提到过在Idea中可以将鼠标停留在方法名上，然后点击F2查看方法的说明，这个说明就是程序员编写的JavaDoc

那我们如何将一个项目中自己编写的JavaDoc生成一个HTML格式的文档呢？

IDEA提供了这个工具，其底层还是 IDEA调用 javadoc.exe（JDK 自带的工具）根据源代码中的注释内容自动生成 JavaDoc 文档（超文本格式）。

生成步骤

第一步：打开“生成JavaDoc”对话框

第二步：配置参数

1.一号位置是用于选择JavaDoc的生成范围，这里我们指定的是当前的Module，如果有需求的话也可以指定特定文件

2.二号位置用于指定文档生成后的输出位置

3.三号位置用于指定需要生成的JavaDoc的以何种语言展示。根据 javadoc.exe 的帮助说明，这其实对应的就是 javadoc.exe 的 -locale 参数，如果不填，默认可能是英文或者是当前操作系统的语言，既然是国人，建议在此填写 zh_CN，这样生成的 JavaDoc 就是中文版本的，当然指的是 JavaDoc 的框架中各种通用的固定显示区域都是中文的。你自己编写的注释转换的内容还是根据你注释的内容来。

4.四号位置用于填写需要传入的参数（非常重要）

这里填写如下参数：

-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。

点击OK后控制台输出下面内容

查看生成的文档

本文章转载至https://www.cnblogs.com/xiaoming0601/p/6657136.html，感谢“小明快点跑”博主对我的帮助。