一、综述
1.简介
Javadoc是Java自带的一种工具，其可以从程序源代码中抽取类、方法、成员等注释形成一个和源代码配套的API帮助文档。也就是说，只要在编写程序时以一套特定的标签作注释，在程序编写完成后，通过Javadoc就可以同时形成程序的开发文档了。
Java中有三种注释方法：
- //被注释语句
- /*被注释语句*/
- /**被注释语句*/
其中第三种专为JavaDoc设计，可以被JDK内置的Javadoc工具支持和处理。
Javadoc在命令行使用还是比较复杂的，在Eclipse、IntelliJ IDEA等IDE中却比较方便，在命令行使用的麻烦的原因是众多的参数。
但是IDE傻瓜型的操作在有些时候还完成不了想要的任务。这时候，就需要懂得一些参数命令的用法了。
生成javadoc 不要求你的java代码是可编译的。唯一要求的是存在.java文件。
官方提供API帮助文档：docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html
常用:
javadoc -d c:/doctest/Rz -sourcepath src -subpackages com -encoding utf-8 -charset utf-8 -windowtitle Rz -doctitle 欢迎使用RzAPI文档 -private -author -version2.生成细节
注释文档的格式：
- 注释文档将用来生成HTML格式的代码报告，所以注释文档必须书写在类、域、构造函数、方法、定义之前。
- 注释文档由两部分组成——描述、块标记。
- 以@开头的是快标记。
Javadoc生成的文档是 HTML 格式，而这些 HTML 格式的标识符并不是 javadoc 加的，而是我们在写注释的时候写上去的。比如，需要换行时，不是敲入一个回车符，而是写入 <br>，如果要分段，就应该在段前写入 <p>。因此，格式化文档，就是在文档注释中添加相应的 HTML 标识。文档注释的正文并不是直接复制到输出文件 (文档的 HTML 文件)，而是读取每一行后，删掉前导的 * 号及 * 号以前的空格，再输入到文档的。
注意：
- 文档注释只说明紧接其后的类、属性或者方法。
2.1描述
方法的简单注释：
注意细节：
- 方法的简单注释，是注释第一行最后一个点号“.”之前的，之后的将在下面详细的叙述部分出现。
- 如果方法简述的第一行最后没有点号（哪怕中间有点好），解析的时候会自动查找下面行的最近最后出现行末尾的点号。
详细细节：除了简单叙述外，其它部分的叙述也会出现在下面的详细叙述部分，也就是上面超链接的部分。
2.2块标记
快标记以@开头。
常用的快标记包括：
@author 标明开发该类模块的作者
@version 标明该类模块的版本
@see 参考转向，也就是相关主题
@param 对方法中某参数的说明
@return 对方法返回值的说明
@exception 对方法可能抛出的异常进行说明
2.3快标记的顺序（Order of Tags）
- @author (classes and interfaces only, required)
- @version (classes and interfaces only, required. See footnote 1)
- @param (methods and constructors only)
- @return (methods only)
- @exception (@throws is a synonym added in Javadoc 1.2)
- @see
- @since
- @serial (or @serialField or @serialData)
- @deprecated (see How and When To Deprecate APIs)
2.4可以多次使用标签（Ordering Multiple Tags）
- @author标签应按时间顺序排列，并用逗号分隔。
- @ param标签应该在参数声明的顺序列出，这使它更容易在视觉上与声明相匹配的列表。
- @throws标签 (类同 @exception)应按字母顺序列出的例外的名字。
- @see标签遵循由近到远，参数由少到多，由上到下的顺序。
- @see #field
- @see #Constructor(Type, Type...)
- @see #Constructor(Type id, Type id...)
- @see #method(Type, Type,...)
- @see #method(Type id, Type, id...)
- @see Class
- @see Class#field
- @see Class#Constructor(Type, Type...)
- @see Class#Constructor(Type id, Type id)
- @see Class#method(Type, Type,...)
- @see Class#method(Type id, Type id,...)
- @see package.Class
- @see package.Class#field
- @see package.Class#Constructor(Type, Type...)
- @see package.Class#Constructor(Type id, Type id)
- @see package.Class#method(Type, Type,...)
- @see package.Class#method(Type id, Type, id)
- @see package
二、详解
1.方法及类上注解
1.1@category
作用：
详细使用实例：
1.2@deprecated（since 1.0）
作用：引起不推荐使用的警告（API中会显示已过时，类名/方法名上会有一个划去的横杠）
详细使用示例：@deprecated
针对过时警告，往往伴随的是指向替代方法。An @see tag (for Javadoc 1.1) or {@link} tag (for Javadoc 1.2 or later) should be included that points to the replacement method
针对1.2及之后版本
- /**
- * @deprecated As of JDK 1.1, replaced by
- * {@link #setBounds(int,int,int,int)}
- */
- /**
- * @deprecated As of JDK 1.1, replaced by setBounds
- *
- *
- * @see #setBounds(int,int,int,int)
- */
1.3@see（since 1.0）
作用：参考转向，@ see标签可以创建链接到其他javadoc文档的交叉引用。
详细使用示例：
- @see 类名
- @see 完整类名
- @see 完整类名#方法名
- @see 上面三种之一 别名
注意：
- 上面每种格式都会在生成的文档里自动生成一个超链接的条目，但是JavaDoc不会检查我们指定的超链接，不会验证它们是否有效。
- 当前包中的类或者方法以及接口，可以使用类名，或者类名#方法名来指定
- 其它包中的，我们必须使用完全限定名
- /**
- * @see String
- * @see java.lang.StringBuffer
- * @see #str
- * @see #str()
- * @see #main(String[])
- * @see Object#toString()
- */
String 和 StringBuffer 都是在 java.lang 包中，由于这个包是默认导入了的，所以这两个类可以直接写类名，也可以写类全名。str、str() 为同名属性和方法，所以方法名需要用 () 区分。main 是带参数的方法，所以在 () 中指明了参数类型。toString() 虽然在本类中也有 (从 Object 继承的)，但我们是想参考 Object 类的 toString() 方法，所以使用了 Object#toString()。
奇怪的是，为什么其中只有 str、str() 和 main(String[]) 变成了链接呢？那是因为编译时没有把 java.lang 包或者 Stirng、StringBuffer、Object 三个类的源文件一起加入编译，所以，生成的文档没有关于那三个类的信息，也就不可以建立链接了。后面讲解 javadoc 编译命令的时候还会详细说明。
上例中如果去把类中的 str 属性去掉，那么生成的文档又会有什么变化呢？你会发现，原来是 str, str()，而现在变成了 str(), str()，因为 str 属性已经没有了，所以 str 也表示方法 str()。
1.4@since（since 1.1）
作用：最早使用该方法/类/接口的版本
详细使用示例：@since 版本号
1.5{@code}（since 1.5）
作用：声明下面的是代码注释
详细使用实例：
{@code
代码
}
注意：使用的时候，必须借助html标签<pre></pre>，否则样式是无法保留的。
使用方式：<pre>{@code代码}</pre>
1.6{@docRoot}（since 1.3）
作用：
详细使用实例：
1.7{@linkplain}（since 1.4）
作用：
详细使用实例：
1.8{@link}（since 1.2）
作用：
详细使用实例：
1.9{@literal}（since 1.5）
作用：
详细使用实例：
1.10{@value}（since 1.4）
作用：
详细使用实例：
2.类上注解
2.1@author（since 1.0）
作用：标明开发该类模块的作者。
详细使用示例：@author 姓名
- @author Fancy<br>Bird
2.2@version（since 1.0）
作用：该类模块的版本
详细使用示例：@version 版本号
注意：此标签可以使用多次，但是只有第一次有效。
2.3@serial（since 1.2）
作用：
详细使用实例：
3.方法&接口上注解
3.1@exception&@throws（since 1.0&1.2）
@throws以前使用的是@exception
作用：对方法可能抛出的异常进行说明
详细使用示例：（使用方式一样）@throws 异常类名 对异常的解释说明
3.2@return（since 1.0）
作用：对方法返回值的说明
详细使用示例：@return 返回值解释说明
3.3@param（since 1.0）
作用：对方法中的参数进行说明，我们应该针对方法的每一个参数都使用一个该标签。
详细使用示例：@param 参数名 参数的解释说明
3.4@serialData（since 1.2）
作用：
详细使用实例：
3.5{@inheritDoc}（since 1.4）
作用：
详细使用实例：
三、控制台
虽然使用IDE会非常简单，但是，IDE中还需要使用到各种控制台参数，所以，这里先介绍使用控制台。
首先通过命令，查看控制台辅助信息：
- C:\Users\fxb>javadoc -help
- 用法: javadoc [options] [packagenames] [sourcefiles] [@files]
- -overview <file> 从 HTML 文件读取概览文档
- -public 仅显示 public 类和成员
- -protected 显示 protected/public 类和成员 (默认值)
- -package 显示 package/protected/public 类和成员
- -private 显示所有类和成员
- -help 显示命令行选项并退出
- -doclet <class> 通过替代 doclet 生成输出
- -docletpath <path> 指定查找 doclet 类文件的位置
- -sourcepath <pathlist> 指定查找源文件的位置
- -classpath <pathlist> 指定查找用户类文件的位置
- -cp <pathlist> 指定查找用户类文件的位置
- -exclude <pkglist> 指定要排除的程序包列表
- -subpackages <subpkglist> 指定要递归加载的子程序包
- -breakiterator 计算带有 BreakIterator 的第一个语句
- -bootclasspath <pathlist> 覆盖由引导类加载器所加载的
- 类文件的位置
- -source <release> 提供与指定发行版的源兼容性
- -extdirs <dirlist> 覆盖所安装扩展的位置
- -verbose 输出有关 Javadoc 正在执行的操作的信息
- -locale <name> 要使用的区域设置, 例如 en_US 或 en_US_WIN
- -encoding <name> 源文件编码名称
- -quiet 不显示状态消息
- -J<flag> 直接将 <flag> 传递到运行时系统
- -X 输出非标准选项的提要
- 通过标准 doclet 提供:
- -d <directory> 输出文件的目标目录
- -use 创建类和程序包用法页面
- -version 包含 @version 段
- -author 包含 @author 段
- -docfilessubdirs 递归复制文档文件子目录
- -splitindex 将索引分为每个字母对应一个文件
- -windowtitle <text> 文档的浏览器窗口标题
- -doctitle <html-code> 包含概览页面的标题
- -header <html-code> 包含每个页面的页眉文本
- -footer <html-code> 包含每个页面的页脚文本
- -top <html-code> 包含每个页面的顶部文本
- -bottom <html-code> 包含每个页面的底部文本
- -link <url> 创建指向位于 <url> 的 javadoc 输出的链接
- -linkoffline <url> <url2> 利用位于 <url2> 的程序包列表链接至位于 <ur
- 的文档
- -excludedocfilessubdir <name1>:.. 排除具有给定名称的所有文档文件子目录。
- -group <name> <p1>:<p2>.. 在概览页面中, 将指定的程序包分组
- -nocomment 不生成说明和标记, 只生成声明。
- -nodeprecated 不包含 @deprecated 信息
- -noqualifier <name1>:<name2>:... 输出中不包括指定限定符的列表。
- -nosince 不包含 @since 信息
- -notimestamp 不包含隐藏时间戳
- -nodeprecatedlist 不生成已过时的列表
- -notree 不生成类分层结构
- -noindex 不生成索引
- -nohelp 不生成帮助链接
- -nonavbar 不生成导航栏
- -serialwarn 生成有关 @serial 标记的警告
- -tag <name>:<locations>:<header> 指定单个参数定制标记
- -taglet 要注册的 Taglet 的全限定名称
- -tagletpath Taglet 的路径
- -charset <charset> 用于跨平台查看生成的文档的字符集。
- -helpfile <file> 包含帮助链接所链接到的文件
- -linksource 以 HTML 格式生成源文件
- -sourcetab <tab length> 指定源中每个制表符占据的空格数
- -keywords 使程序包, 类和成员信息附带 HTML 元标记
- -stylesheetfile <path> 用于更改生成文档的样式的文件
- -docencoding <name> 指定输出的字符编码
1.语法
javadoc [ options ] [ packagenames ] [ sourcefilenames ] [ -subpackages pkg1:pkg2:... ] [ @argfiles ]
注意：Arguments can be in any order.（理解：参数没有顺序要求是指的是options的参数，但是包名，以及源文件名等的顺序还是要与上述相同的。）
1.1 options（命令行选项）
上面已经罗列的非常详细了，不过最好是通过直接在控制台查询比较好，因为版本之间会出现细微差别。
下面罗列出常用的命令行选项：
- 设置源码编码方式：-encoding UTF-8
- 指定输出的字符编码：-charset UTF-8
- 自定输出的路径：-d
- 使用的语言环境：-locale zh_CN
- 指定标题栏标题文字：-windowtitle <text>
- 包含概览页面的标题：-doctitle <html-code>
- 包含每个页面的页眉文本：-header <html-code>
- 包含每个页面的页脚文本：-footer <html-code>
- 包含每个页面的顶部文本：-top <html-code>
- 包含每个页面的底部文本：-bottom <html-code>
- 指定查找源文件的位置：-sourcepath <pathlist>
- 指定要递归加载的子程序包：-subpackages <subpkglist>
1.2 packagenames（包名称）
包名称与java的使用规则类同，都是通过点号进行分割，例如：java.lang java.lang.reflect。
注意：你必须分别指明你要生成文档的文件夹，因为 Wildcards(通配符)是无法使用的，Javadoc tool会通过递归的方式，遍寻子文件夹。
cd
) or by using
-sourcepath
option.
- javadoc -d \home\html -sourcepath \home\src -subpackages java -exclude java.net:java.lang
实例二：Run on explicit packages after changing to the "root" source directory（在改变根目录后，运行在明确的包下）
- C:> cd C:\home\src\
- C:> javadoc -d C:\home\html java.awt java.awt.event
示例三： Run from any directory on explicit packages in a single directory tree（一个目录树）
- C:> javadoc -d C:\home\html -sourcepath C:\home\src java.awt java.awt.event
- C:> javadoc -d C:\home\html -sourcepath C:\home\src1;C:\home\src2 java.awt java.awt.event
1.3 sourcefilenames（源文件名称）
- C:> cd C:\home\src\java\awt
- C:> javadoc -d C:\home\html Button.java Canvas.java Graphics*.java
- C:> cd C:\home\src
- C:> javadoc -d \home\html java\awt\Button.java java\applet\Applet.java
- C:> javadoc -d C:\home\html C:\home\src\java\awt\Button.java C:\home\src\java\awt\Graphics*.java
- C:> javadoc -d C:\home\html -sourcepath C:\home\src java.awt C:\home\src\java\applet\Applet.java
1.4-subpackages pkg1:pkg2:...
Generates documentation from source files in the specified packages and recursively in their subpackages. An alternative to supplying packagenames or sourcefilenames.1.5@argfiles
2.细节
2.1不比指定源文件名称的三种情况
- 指定包名称
- 使用子包
- 使用通配符
- 文件名称必须以.java结尾，并且文件名是一个合法的类名。
- 相对于根目录路径需要是一个合法的包名（以点号进行分割的形式）
- 包名称必须是一个合法的
四、IDE集成
Export(导出)——>找到java下的Javadoc——>设置好各个选项——>设置控制台的参数列表
Eclipse Java注释模板设置详解
设置注释模板的入口： Window->Preference->Java->Code Style->Code Template 然后展开Comments节点就是所有需设置注释的元素。
https://blog.youkuaiyun.com/fanxiaobin577328725/article/details/52658781
http://showlike.iteye.com/blog/1552942
https://blog.youkuaiyun.com/psy1100/article/details/51179342
扫一扫
2353
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
