写这篇文章完全是一时兴起，因为在此之前，我其实也并没有使用过 Java Doc 的功能。但是即使很少使用得到，但是你不得不承认，如果公司的API能够整理出这么一套API，我想每一个刚入职的员工都会对它爱不释手的。
代码中注释的使用
1. 首先看一个Demo：
import java.util.*;
/**
* @author WithWings
* @version 1.1
* @since 1.8
*/
public class HelloWorld{
public static String hello = "Hello,World!";
public static void main(String[] args){
try{
sayHello(hello);
}catch(Exception e){
e.printStackTrace();
}
}
/**
* 主项目工程执行方法，运行 .class 文件后自动执行 mian方法
* @param s 参数
* @return 返回的参数
* @see Image
* @see #hello
* @exception Exception 提供异常处理 方法一
* @throws Exception 提供异常处理 方法二
*/
public static String sayHello(String s) throws Exception{
System.out.println(s);
System.out.println(new Date());
try{
Thread.currentThread().sleep(5 * 1000);
}catch( InterruptedException e){
e.printStackTrace();
}
return s;
}
public class Image{
/**
* @deprecated 标记该API过时
*/
public void printImage(){
System.out.println("Image");
}
}
}
- @author 作者（只出现在类和接口的文档中）
- @version 数字指的是版本号
- @since 数字指的jdk版本
- @param 指的是方法的参数，后面跟上 参数名 + 空格 + 参数说明
- @return 对返回值的说明
- @see 添加引用的类或者参数
- @see 类名
- @see #方法名或参数名
- @see 类名#参数名
- @throws 抛出异常说明， 后面跟上 异常名 + 空格 + 异常跑出原因
2. 上面是我自己用到的，然而这些并不是很齐全，但是很幸运，我在极客学院找到一个表格，图省事我就直接copy过来了。
| 标签 | 描述 | 语法 | ||
|---|---|---|---|---|
| @author | 添加类的作者 | @author name-text | ||
| {@code} | 不把文本转换成 HTML 标记和嵌套的 Java 标签而用代码字体展示它 | {@code text} | ||
| {@docRoot} | 表示从任何生成页面到生成文档的根目录的相对路径 | {@docRoot} | ||
| @deprecated | 添加一个注释暗示 API 应该不再被使用 | @deprecated deprecated-text | ||
| @exception | 用类名和描述文本给生成的文档添加一个副标题 | @exception class-name description | ||
| {@inheritDoc} | 从最近的可继承的类或可实现的接口继承注释 | Inherits a comment from the immediate surperclass. | ||
| {@link} | 用指向特定的包，类或者一个引用类的成员名的文档的可见文本标签插入在线链接 | {@link package.class#member label} | ||
| {@linkplain} | 和{@link}相同，除了链接的标签用纯文本标示而不是代码字体 | {@linkplain package.class#member label} | ||
| @param | 给“参数”区域添加一个有特定参数名且后跟着特定描述的参数 | @param parameter-name description | ||
| @return | 添加一个有描述文本的“Returns”区域 | @return description | ||
| @see | 添加带有链接或者指向引用的文本入口的标题“See Also” | @see reference | ||
| @serial | 在默认的序列化字段的文本注释中使用 | @serial field-description | include | exclude |
| @serialData | 记录由 writeObject( ) 或 writeExternal( )方法所写的数据 | @serialData data-description | ||
| @serialField | 记录一个 ObjectStreamField 成分 | @serialField field-name field-type field-description | ||
| @since | 给生成的文档添加一个带有特定 since 文本的”Since”标题 | @since release | ||
| @throws | @throw 和 @exception 标签是同义词 | @throws class-name description | ||
| {@value} | 当{@value}被用在一个静态字段的文本注释中，它展示了那个常量的值 | {@value package.class#field} | ||
| @version | 当 -version 选项被使用时用特定的 version w文本给生成的文本添加一个“Version”副标题 | @version version-text |
3. 接下来就是最后一步，生成了，说实话，我之前不使用Java Doc 的原因，很大一部分就是因为，生成命令过于复杂了。但是这次，我做了一个仔细的分析，力求可以清晰的使用，并且总结两条常用的可以让大家直接复制生成doc的常用命令。
-
单个Java文件：
javadoc -locale zh_CN -d [apidoc] -windowtitle [title] -doctitle [doctitle] -encoding UTF-8 -charset UTF-8 *HelloWorld.java[apidoc] : 替换成希望生成的doc文档名
[title] : 替换成网页标题
[doctitle] : 替换成文档题目
[*HelloWorld.java] : 替换成要编译的文件 -
多文件多包：
包的根目录处新建 packagepath.txt 文件：
内容为每个类所在的包名，这个不适用通配符，不会自动读取子目录，所以要把所有用到的全部列出来，中间使用空格隔开，没有办法读取根目录处的java文件。
javadoc -locale zh_CN -d [apidoc] -windowtitle [title] -doctitle [doctitle] -encoding UTF-8 -charset UTF-8 @packagepath.txt或者直接：
javadoc -locale zh_CN -author -version -d [apidoc] -windowtitle [title] -doctitle [doctitle] -encoding UTF-8 -charset UTF-8 @packagepath.txt[apidoc] : 替换成希望生成的doc文档名
[title] : 替换成网页标题
[doctitle] : 替换成文档题目
[*HelloWorld.java] : 替换成要编译的文件 -
想要包含版本号和作者的话，在 -locale zh_CN 后添加 -author -version
javadoc -locale zh_CN -author -version -d [apidoc] -windowtitle [title] -doctitle [doctitle] -encoding UTF-8 -charset UTF-8 包名1 包名2 包名3
4. 详细的命令使用，有心研究的可以看一下
javadoc -help
用法：javadoc [选项] [软件包名称] [源文件] [@file]
-overview <文件> 读取 HTML 文件的概述文档
-public 仅显示公共类和成员
-protected 显示受保护/公共类和成员（默认）
-package 显示软件包/受保护/公共类和成员
-private 显示所有类和成员
-help 显示命令行选项并退出
-doclet <类> 通过替代 doclet 生成输出
-docletpath <路径> 指定查找 doclet 类文件的位置
-sourcepath <路径列表> 指定查找源文件的位置
-classpath <路径列表> 指定查找用户类文件的位置
-exclude <软件包列表> 指定要排除的软件包的列表
-subpackages <子软件包列表> 指定要递归装入的子软件包
-breakiterator 使用 BreakIterator 计算第 1 句
-bootclasspath <路径列表> 覆盖引导类加载器所装入的
类文件的位置
-source <版本> 提供与指定版本的源兼容性
-extdirs <目录列表> 覆盖安装的扩展目录的位置
-verbose 输出有关 Javadoc 正在执行的操作的消息
-locale <名称> 要使用的语言环境，例如 en_US 或 en_US_WIN
-encoding <名称> 源文件编码名称
-quiet 不显示状态消息
-J<标志> 直接将 <标志> 传递给运行时系统
通过标准 doclet 提供：
-d <目录> 输出文件的目标目录
-use 创建类和软件包用法页面
-version 包含 @version 段
-author 包含 @author 段
-docfilessubdirs 递归复制文档文件子目录
-splitindex 将索引分为每个字母对应一个文件
-windowtitle <文本> 文档的浏览器窗口标题
-doctitle <html 代码> 包含概述页面的标题
-header <html 代码> 包含每个页面的页眉文本
-footer <html 代码> 包含每个页面的页脚文本
-bottom <html 代码> 包含每个页面的底部文本
-link <url> 创建指向位于 <url> 的 javadoc 输出的链接
-linkoffline <url> <url2> 利用位于 <url2> 的软件包列表链接至位于 <url>
的文档
-excludedocfilessubdir <名称 1>:..排除带有给定名称的所有文档文件子目录。
-group <名称> <p1>:<p2>.. 在概述页面中，将指定的软件包分组
-nocomment 抑止描述和标记，只生成声明。
-nodeprecated 不包含 @deprecated 信息
-noqualifier <名称 1>:<名称 2>:...从输出中排除限定符的列表。
-nosince 不包含 @since 信息
-notimestamp 不包含隐藏时间戳
-nodeprecatedlist 不生成已过时的列表
-notree 不生成类分层结构
-noindex 不生成索引
-nohelp 不生成帮助链接
-nonavbar 不生成导航栏
-serialwarn 生成有关 @serial 标记的警告
-tag <名称>:<位置>:<标题> 指定单个变量自定义标记
-taglet 要注册的 Taglet 的全限定名称
-tagletpath Taglet 的路径
-charset <字符集> 用于跨平台查看生成的文档的字符集。
-helpfile <文件> 包含帮助链接所链接到的文件
-linksource 以 HTML 格式生成源
-sourcetab <制表符长度> 指定源中每个制表符占据的空格数
-keywords 使软件包、类和成员信息附带 HTML 元标记
-stylesheetfile <路径> 用于更改生成文档的样式的文件
-docencoding <名称> 输出编码名称
5. 最后放上一个超简单的命令，但是貌似很容易出问题：
javadoc AddNum.java
如果你正在使用 JDK 1.7 那么 Javadoc 不会生成 stysheet.css，所以我建议直接下载一份，然后放进生成的index.html同级目录即可：右键链接另存为