Javadoc使用规范以及生成

注释文档格式

• 注释文档是用来生成HTML格式的代码报告，所以注释文档必须书写在类、域、构造函数、方法定义之前。
• 注释文档由两部分组成：描述和标记
• 以@开头的为标记

注意：javadoc需要添加响应的HTML标识，Javadoc 生成的文档是 HTML 格式，而这些 HTML 格式化的标识符并不是 javadoc 加的，而是我们在写注释的时候写上去的。比如，需要换行时，不是敲入一个回车符，而是写入 <br />，如果要分段，就应该在段前写入 <p>。

描述

• 方法的简单注释，是注释第一行最后需要加“.”。
• 如果方法描述的第一行没有“.”，解析的时候会自动查找到下面行中最近的行末尾最后出的“.”。
• 简单注释的第一行末尾的“.”后使用<br />进行换行.

标记

标记全部是以@开头

标记的顺序

• @author (类和接口上使用)
• @version (类和接口上使用)
• @param (方法和构造函数使用)
• @return (仅方法使用)
• @exception (@throws代替)
• @see
• @since
• @deprecated

可以多次使用的标记

• @author 标记应按时间顺序排列，并用逗号分隔。
• @param 标记应该在参数声明的顺序列出，这使它更容易在视觉上与声明相匹配的列表。
• @throws 标记 (类同 @exception)应按字母顺序列出的例外的名字。
• @see 标记遵循由近到远，参数由少到多，由上到下的顺序

标记详解

1. @deprecated
   • 语法：@deprecated deprecated-text
   • 作用：表明当前的方法或类已过时（类名或者方法名上有一个划去的横杠）
2. @since
   • 语法：@since since-text
   • 作用：最早使用该方法/类/接口的版本
3. {@code}
   • 语法：{@code text}
   • 作用：声明其中的内容是代码注释
   • 注意：使用的时候，必须借助 html 标签<pre>，否则样式是无法保留的。
   • 使用方式：<pre>{@code代码}</pre>
4. {@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) {
     }
     

5. @author
   • 语法：@author name-text
   • 作用：标明开发该类模块的作者。
6. @version
   • 语法：@version version-text
   • 作用：该类模块的版本
   • 注意：这个标记可以多次使用，但是只有第一次有效
7. @exception @throws
   • @throws 以前使用的是 @exception
   • 语法：@throws class-name description
   • 作用：对方法可能抛出的异常进行说明
8. @return
   • 语法：@return description
   • 作用：对方法返回值的说明
9. @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】,选择合适的方法，如图：

效果

创建类

创建方法