注释文档格式
- 注释文档是用来生成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}
- 语法：{@value package.class#field}
- 作用：值引用
当在静态字段的注释中使用{@value}时(没有任何参数)，它将显示该常量的值： /** * The value of this constant is {@value}. */ public static final String SCRIPT_START = "script"; 当在任何doc注释中与参数 package.class#field 字段一起使用时，它将显示指定常量的值： /** * Evaluates the script starting with {@value #SCRIPT_START}. */ public String evalScript(String script) { }
- @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】。
- Avvreviation：输入快捷键（我用的method，在方法上输入method+回车就可以看到注释了）
- Description：注释模板的描述
- Template test：注释模板的动态内容
/** * @param $params$ * @return $returns$ * @date $date$ $Time$ */
点击右侧的【Edit variables】,选择合适的方法，如图：
效果
创建类
创建方法
