java开发注释规范插件_Java 注释规范

我是清都山水郎，天教懒慢带疏狂。曾批给露支风券，累奏流云借月章。

诗万首，酒千觞，几曾着眼看侯王。玉楼金阙慵归去，且插梅花醉洛阳。

1、概览

好的注释往往能减少提供协同开发的工作效率，以及极大的提升系统的可维护性。因此写好代码注释也是一个很重要的事情。

Javadoc 一般分为三段：第一段：概要描述

通常用一句话描述类或方法的作用，且以 . 结尾

第二段：详细描述

第三段：文档标注，用于标注作者、创建时间、参阅类等信息。

效果图

2、注释介绍

以下只介绍常用的注释标签描述作用域@author标注类的作者类

@deprecated标注类或者方法过时类、方法

@exception标注方法抛出的异常方法

@throws与 @exception 一致方法

{@inheritDoc}从直接父类继承的注释类、方法

{@link}插入一个到另外一个主题的链接类、方法

@param说明方法参数方法

@return说明方法返回值方法

@see指定一个到另一个主题的链接类、方法

@since标记从什么时候引入的类、方法

@version指定类的版本类

{@value}显示常量的值需要被 final 修饰

3、demo/**

* 订单服务类

*

* @author 陈少平

* @version 1.0

*/

public interface OrderService {

/**

* 订单状态,表示关闭 {@value}

*

* @see OrderType

*/

int STATUS_CLOSE = 1;

/**

* 获取订单号.

*

* 订单号生成格式如下

*

{@code

* String sn = orderId + RandomUtil.randomLong()

* }

*

* @param orderId 订单id

* @param orderType {@link OrderType}

* @exception IOException 读取订单失败

* @throws NullPointerException 如果 {@code orderId} null.

* @return {@literal }

*

* @since 1.2

* @see OrderType#success

*/

Map getOrderSn(Long orderId, int orderType) throws IOException;

/**

* @deprecated 获取订单状态.

*

* @param orderId 订单id

* @return 订单状态

*

* @since 1.0

* @see OrderType#success

* @see OrderType#cancle

*/

int getStatus(Long orderId);

}

4、生成 Javadocmaven 中引入 javadoc 插件

org.apache.maven.plugins

maven-javadoc-plugin

utf-8

utf-8

true

none

attach-javadocs

jar

执行 mvn javadoc:javadoc

执行完命令后，会在 target/site/apidocs 目录下生成 html 文件既然选择了远方，即使天寒地冻，路遥马亡，我本就一无所有，又有何惧。