javadoc的标签和规则

javadoc的标签和规则

前言

因最近一直在研读JDK的源码,深刻理解javadoc就是作者和读者交流最好的渠道,好的注释言简意赅的说明了包、类、方法、字段、构造函数的意图。受此影响,最近的工作中我也尝试在自己的代码里添加javadoc的详细说明。但因并不系统的了解它,写起来吭吭呲呲,比较费力,于是诞生了这篇文章。

注释源码

  • 一段注释开始于/**,结束于*/。如果有多行,每行都包含前导*
1
2
3
4
/**
* This is the typical format of a simple documentation comment
* that spans two lines.
*/
  • 注释只能紧挨着放置在class,interface,construct,method,field上方。一个常见的错误是将class注释也在import上。
1
2
3
4
5
6
7
8
/**
* This is the class comment for the class Whatever.
*/
import com.sun; // MISTAKE - Important not to put import statement here
public class Whatever {
}
  • 注释由两个部分组成,主要描述和标签部分。
1
2
3
4
/**
* This sentence would hold the main description for this doc comment.
* @see java.lang.Object
*/
  • 标签有两种类型:块标签和内联标签。块标签的写法@tag,内联标签的写法{@tag}。为了正确被解析,块标签必须出现在行的开始,而内联标签可以随意出现在任何地方。
1
2
3
/**
* @deprecated As of JDK 1.1, replaced by {@link #setBounds(int,int,int,int)}
*/
  • 注释最终呈现是html格式,所以可以直接使用Html的标签或Html实体。
1
2
3
4
/**
* This is a <b>doc</b> comment &amp; that's all.
* @see java.lang.Object
*/
  • 当javadoc解析注释,前导*会被移除。*前的空格或tab也会被移除。
  • 每段注释的第一句话都应当简短概要。界定第一句话标准是遇到空格tab.或者块标签。第一句话会当作摘要出现在概要表格中。
  • 尽量不要使用<h1><h2>标签,可能会破坏javadoc的结构
  • 可以支持对多个字段的注释
1
2
3
4
/**
* The horizontal and vertical distances of point (x,y)
*/
public int x, y; // Avoid this

生成的注释如下

1
2
3
4
public int x
The horizontal and vertical distances of point (x,y)
public int y
The horizontal and vertical distances of point (x,y)

注释继承

以下两种情况下,method级别的注释可以被继承,构造函数、字段和内部类级别不可以。

  • 信息丢失。主要信息或者@return @param @throw标签丢失。
  • 显式使用@inheritDoc标签。

注释继承自classinterface,有以下三种情况

  1. class重写父类的方法
  2. interface重写父接口的方法
  3. class实现interface方法

前两种情况,会生成”Overrides”副标题,第3种情况,会生成“Specified by”副标题。

方法注释的继承算法

  1. 查找每一个直接继承或者实现的interface,顺序是出现在implements/extends的顺序,使用第一个查找到的注释继承。
  2. 如果1失败,对1种直接继承或者实现的interface,递归的使用1的算法。
  3. 如果2失败,并且这是一个非Objectclass而不是interface
    • 如果superclass有注释,继承之。
    • 如果没有,递归的使用3.1中的算法查找父类。

标签

标签列表

author
  • 格式
    @author name-text
  • 描述
    说明代码的作者
  • 示例
1
2
3
4
5
6
/**
* @author john, johnson
* 等价于
* @author john
* @author johnson
*/
deprecated
  • 格式
    @deprecated deprecated-text
  • 描述
    标识元素已经被废弃,后面的描述会被移到main description之前。描述至少要告诉用户什么时候开始废弃和替代方法。之后可以介绍为什么被废弃。
  • 示例
1
2
3
/**
* @deprecated As of JDK 1.1, replaced by {@link #setBounds(int,int,int,int)}
*/
code和literal
  • 格式
    {@code text}
  • 描述
    标签中的文本不会被转义成html代码,可以放心使用> <。
  • 示例
1
2
3
4
5
/**
* {@code A<B>C}
* 等价于
* {@literal A<B>C}
*/
docRoot
  • 格式
    {@docRoot}
  • 描述
    javadoc的根目录相对路径。
  • 示例
1
2
3
/**
* See the <a href="{@docRoot}/copyright.html">Copyright</a>.
*/
exception和throws
  • 格式
    @throws class-name description
  • 描述
    此二者是同义词。说明方法可能抛出的异常以及其描述。只能用在methodconstructor,可多次使用。如果代码中的throw的异常未被记录,javadoc tool会自动将其添加到文档中。

  • 示例

1
2
3
/**
* @throws IllegalArgumentException argument illegal
*/
inheritDoc
  • 格式
    {@inheritDoc}
  • 描述
    拷贝“最近”的注释,算法如上。这个标签只能使用在两个地方

    - `method`的主体描述(main description)
    - `method`的@return、@param、@throws标签的描述
    
  • 示例

1
2
3
/**
* @throws IllegalArgumentException {@inheritDoc}
*/
link和linkplain
  • 格式
    {@link package.class#member label}
  • 描述
    插入一条指向指定packageclassmember显示文本为label的链接。这个标签跟@see很相似,有着相同的语法。主要的不同是{@link}可以在任何地方插入一个链接,而@see只能当做块标签。linkplain的用法同link,只是linkplain的label是文本字体而link的是code字体。

  • 示例

1
2
3
4
/**
* Use the {@link #getComponentAt(int, int) getComponentAt} method.
* Use the {@linkplain #getComponentAt(int, int) getComponentAt} method.
*/
param
  • 格式
    @param parameter-name description
  • 描述
    参数的注释,只能用在class/method/constructor上。
  • 示例
1
2
3
4
5
6
7
8
/**
* @param string the string to be converted
* @param type the type to convert the string to
* @param <T> the type of the element
* @param <V> the value of the element
*/
<T, V extends T> V convert(String string, Class<T> type) {
}
return
  • 格式
    @return description
  • 描述
    返回值的注释,需要描述返回的类型和内容,只能用在method上。
  • 示例
1
2
3
4
5
/**
* @return the value of the element
*/
<T, V extends T> V convert(String string, Class<T> type) {
}
see
  • 格式
    • @see “string”
    • @see label
    • @see package.class#member label
  • 描述
  • 示例
1
2
3
/**
* @see String#equals(Object) equals
*/
since
  • 格式
    @since since-text
  • 描述
    说明特性自某一版本实现
  • 示例
1
2
3
/**
* @since 1.5
*/
value
  • 格式
    {@value package.class#field}
  • 描述
    当没有参数时,value使用在静态字段,展示的是常量的值。当有参数时,展示的是指定的常量值。
  • 示例
1
2
3
4
/**
* The value of this constant is {@value}.
*/
public static final String SCRIPT_START = "<script>"
version
  • 格式
    @version version-text
  • 描述
    描述当前软件的版本
  • 示例
1
2
3
4
/**
* Created by john on 16/7/20.
* @version 1.1
*/

使用范围

Class/Interface Tags

  • @see
  • @since
  • @deprecated
  • @author
  • @version
  • {@link}
  • {@linkplain}
  • {@docRoot}

Method/Constructor Tags

  • @see
  • @since
  • @deprecated
  • @param
  • @return
  • @throws and @exception
  • {@link}
  • {@linkplain}
  • {@inheritDoc}
  • {@docRoot}

Field Tags

  • @see
  • @since
  • @deprecated
  • {@link}
  • {@linkplain}
  • {@value}
  • {@docRoot}

参考

作者: wuzhaoyang(John)
出处: http://wuzhaoyang.me/
因为作者水平有限,无法保证每句话都是对的,但能保证不复制粘贴,每句话经过推敲。希望能表达自己对于技术的态度,做一名优秀的软件工程师。