JavaDoc 使用详解

1.文档标记

在注释中出现以@开头东东被称之为Javadoc文档标记，是JDK定义好的，如@author、@version、@since、@see、@link、@code、@param、@return、@exception、@throws等。

1.@link:{@link 包名.类名#方法名(参数类型)}用于快速链接到相关代码

2.@code:{@code text}将文本标记为code

3.@param

一般类中支持泛型时会通过@param来解释泛型的类型

4.@author

详细描述后面一般使用@author来标记作者，如果一个文件中有多个作者来维护就标记多个@author，@author后面可以跟作者姓名（也可以附带邮箱地址）、组织名称（也可以附带组织官网地址）

//纯文本作者
@author Mingcai Xiao

//纯文本作者，邮件
@author Mingcai Xiao，mingcaixiao.org

//超文本邮件 纯文本作者
@author <a href="mailto:mingcaixiao@qq.com">Mingcai Xiao</a>

//纯文本邮件
@author mingcaixiao@qq.com

//纯文本组织
@author Apache Software Foundation

//超链接组织地址 纯文本组织
@author <a href="https://mingcaixiao.org">Mingcaixiao</a>

5.@see 另请参阅

@see一般用于标记该类相关联的类，@see既可以用在类上，也可以用在方法上

6.@since 从以下版本开始

@since 一般用于标记文件创建时项目当时对应的版本，一般后面跟版本号，也可以跟一个时间，表示文件当时创建的时间

7.@version 版本

@version 用于标记当前版本，默认为1.0

8.@param

@param 后面跟参数名，再跟参数描述

/**
* @param str the {@code CharSequence} to check (may be {@code null})
*/
public static boolean containsWhitespace(@Nullable CharSequence str) {}

9.@return

@return跟返回值的描述

/**
* @param str the {@code CharSequence} to check (may be {@code null})
*/
public static boolean containsWhitespace(@Nullable CharSequence str) {}

10.@throws

@thorows跟异常描述

2.写在类上面的Javadoc

  • 第一段：概要描述,通常用一句或者一段话简要描述该类的作用，以英文句号作为结束
  • 第二段：详细描述，通常用一段或者多段话详细描述该类的作用，一般每段话都以英文句号作为结束
  • 第三段：文档标注，用于标注作者、创建时间、参阅类等消息

3.写在方法上的JavaDoc

  • 第一段：概要描述,通常用一句或者一段话简要描述该方法的作用，以英文句号作为结束
  • 第二段：详细描述，通常用一段或者多段话详细描述该方法的作用，一般每段话都以英文句号作为结束
  • 第三段：文档标注，用于标注参数、返回值、异常、参阅等