注释文档格式
- 注释文档是用来生成HTML格式的代码报告,所以注释文档必须书写在类、域、构造函数、方法定义之前。
- 注释文档由两部分组成:描述和标记
- 以@开头的为标记
注意:javadoc需要添加响应的HTML标识,Javadoc 生成的文档是 HTML 格式,而这些 HTML 格式化的标识符并不是 javadoc 加的,而是我们在写注释的时候写上去的。比如,需要换行时,不是敲入一个回车符,而是写入 <br />
,如果要分段,就应该在段前写入 <p>
。
描述
- 方法的简单注释,是注释第一行最后需要加
“.”
。
- 如果方法描述的第一行没有
“.”
,解析的时候会自动查找到下面行中最近的行末尾最后出的“.”
。
- 简单注释的第一行末尾的
“.”
后使用<br />
进行换行.
标记
标记全部是以@开头
标记 | 描述 | 引入版本 |
@author | 标明开发该模块的作者 | 1.0 |
@deprecated | 标明方法或类已过时 | 1.0 |
@exception | 对方法可能抛出的异常进行说明【@throws取代】 | 1.0 |
@param | 对方法参数的说明 | 1.0 |
@return | 对方法返回值的说明 | 1.0 |
@see | 参考转向,也就是相关主题 | 1.0 |
@since | 引入的版本 | 1.1 |
@throws | 对方法可能抛出的异常进行说明 | 1.2 |
@version | 表明该类模块的版本 | 1.2 |
{@code} | 标明内部是代码示例 | 1.5 |
{@value} | 值引用 | 1.4 |
{@inheritDoc} | 继承的时候Copy父类的注释 | 1.4 |
标记的顺序
- @author (类和接口上使用)
- @version (类和接口上使用)
- @param (方法和构造函数使用)
- @return (仅方法使用)
- @exception (@throws代替)
- @see
- @since
- @deprecated
可以多次使用的标记
- @author 标记应按时间顺序排列,并用逗号分隔。
- @param 标记应该在参数声明的顺序列出,这使它更容易在视觉上与声明相匹配的列表。
- @throws 标记 (类同 @exception)应按字母顺序列出的例外的名字。
- @see 标记遵循由近到远,参数由少到多,由上到下的顺序
标记详解
- @deprecated
- 语法:@deprecated deprecated-text
- 作用:表明当前的方法或类已过时(类名或者方法名上有一个划去的横杠)
- @since
- 语法:@since since-text
- 作用:最早使用该方法/类/接口的版本
- {@code}
- 语法:{@code text}
- 作用:声明其中的内容是代码注释
- 注意:使用的时候,必须借助 html 标签
<pre>
,否则样式是无法保留的。
- 使用方式:
<pre>
{@code代码}</pre>
- {@value}
- @author
- 语法:@author name-text
- 作用:标明开发该类模块的作者。
- @version
- 语法:@version version-text
- 作用:该类模块的版本
- 注意:这个标记可以多次使用,但是只有第一次有效
- @exception @throws
- @throws 以前使用的是 @exception
- 语法:@throws class-name description
- 作用:对方法可能抛出的异常进行说明
- @return
- 语法:@return description
- 作用:对方法返回值的说明
- @param
- 语法:@param parameter-name description
- 作用:对方法中的参数进行说明,我们应该针对方法的每一个参数都使用一个该标记。
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>
生成文档时,出现中文乱码,直接使用-encoding UTF-8 -charset UTF-8。
设置idea的创建文件的注释模板
依次点击【File】 -> 【Settings】 -> 【Editor】 -> 【File and Code Templates】,修改Class/interface/Enum等注释模板即可
/**
* @author ${USER} // 这里是获取了机器的名字
* @Description // 用来写类的描述
* @date ${DATE} ${TIME} // 创建日期
* @version 1.0 // 版本
*/
设置idea的动态注释模板
依次点击【File】 -> 【Settings】 -> 【Editor】 -> 【Live Templates】
点击【+】号,选择【2.Template Group】,起一个名字,点击OK。

选择刚才见的TemplateGroup,再次点击【+】,选择【1.Live Templates】。

点击右侧的【Edit variables】,选择合适的方法,如图:

效果
创建类

创建方法
