一、综述(类注释及方法注释)
1.1 简介
Javadoc 是 Java 自带的一种工具,其可以从程序源代码中抽取类、方法、成员等注释形成一个和源代码配套的API帮助文档。也就是说,只要在编写程序时以一套特定的标记【Tag】作注释,在程序编写完成后,通过Javadoc就可以同时形成程序的开发文档了。
Java中有三种注释方法:
- //被注释语句
- /*被注释语句*/
- /**被注释语句*/
其中第三种专为 JavaDoc 设计,可以被 JDK 内置的 Javadoc 工具支持和处理。
Javadoc在命令行使用还是比较复杂的,在Eclipse、IntelliJ IDEA等IDE中却比较方便,在命令行使用的麻烦的原因是众多的参数。
但是IDE傻瓜型的操作在有些时候还完成不了想要的任务。这时候,就需要懂得一些参数命令的用法了。
生成 Javadoc 不要求你的Java代码是可编译的,唯一要求的是存在.java文件。
官方提供API帮助文档:
1.2 生成细节
注释文档的格式:
- 注释文档将用来生成HTML格式的代码报告,所以注释文档必须书写在类、域、构造函数、方法、定义之前。
- 注释文档由两部分组成:描述 和 标记。
- 以@开头的是标记。
Javadoc 生成的文档是 HTML 格式,而这些 HTML 格式化的标识符并不是 javadoc 加的,而是我们在写注释的时候写上去的。比如,需要换行时,不是敲入一个回车符,而是写入
,如果要分段,就应该在段前写入
。因此,格式化文档需要在文档注释中添加相应的 HTML 标识。文档注释的正文并不是直接复制到输出文件 (文档的 HTML 文件),而是读取每一行后,删掉前导的 * 号及 * 号以前的空格,再输出到文档的。
注意:文档注释只说明紧接其后的类、属性或者方法。
描述
方法的简单注释:
注意细节:
- 方法的简单注释,是注释第一行最后一个点号“.”之前的,之后的将在下面详细的叙述部分出现。
- 如果方法简述的第一行最后没有点号(哪怕中间有点好),解析的时候会自动查找到下面行中最近的行末尾最后出现的点号。
- IDE相当智能了,但是在格式化代码的时候原本的换行可能会被打乱,因此简单注释的第一行末尾的点号“.”之后使用
进行换行。
详细细节:除了简单叙述外,其它部分的叙述也会出现在下面的详细叙述部分,也就是上面超链接的部分。
标记
标记以@开头:
Tag【标记】 | 描述 | 引入版本 |
---|---|---|
@author |
标明开发该模块的作者 | 1.0 |
{@code} |
标明内部是代码示例 | 1.5 |
{@docRoot} |
代表生成文档的根目录 | 1.3 |
@deprecated |
标明方法或类已过时 | 1.0 |
@exception |
对方法可能抛出的异常进行说明【@throws取代】 | 1.0 |
{@inheritDoc} |
继承的时候把父类的注释都copy | 1.4 |
{@link} |
内联链接【代码字体格式】 | 1.2 |
{@linkplain} |
内联链接【纯文本字体格式】 | 1.4 |
{@literal} |
显示文本【与<pre> 标签类同】 |
1.5 |
@param |
对方法参数的说明 | 1.0 |
@return |
对方法返回值的说明 | 1.0 |
@see |
参考转向,也就是相关主题 | 1.0 |
@serial |
1.2 | |
@serialData |
1.2 | |
@serialField |
1.2 | |
@since |
引入的版本 | 1.1 |
@throws |
对方法可能抛出的异常进行说明 | 1.2 |
{@value} |
值引用 | 1.4 |
@version |
标明该类模块的版本 | 1.0 |
标记的顺序(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)
可以多次使用标记(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