注释文档格式

  • 注释文档是用来生成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 标记遵循由近到远,参数由少到多,由上到下的顺序

标记详解

  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。
Live Templates

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

  • Avvreviation:输入快捷键(我用的method,在方法上输入method+回车就可以看到注释了)
    method
  • Description:注释模板的描述
  • Template test:注释模板的动态内容
    /**
     * @param $params$
     * @return $returns$
     * @date $date$ $Time$
     */
    

Live Templates Add

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

Edit Variables

效果

创建类

创建类

创建方法

创建方法

Q.E.D.

知识共享署名-非商业性使用-相同方式共享 4.0 国际许可协议

让人非我弱,得志莫离群