Intellij IDEA新建类自动生成JavaDoc注释,一键生成文档

Java技术 潘老师 3年前 (2021-03-19) 6252 ℃ (0) 扫码查看

我们在新建一个类的时候经常忘了写或懒得写Javadoc相关注释,这不利于我们代码的可读性,也会极大增加项目的维护成本,于是可以利用Intellij IDEA工具,进行自动生成标准的模板注释,方便后期维护,而且还可以一键生成整个JavaDoc文档。下面潘老师来带大家演示下该如何实现。

1、配置模板

我们打开:File -> Settings ,弹出”Setting对话框”

2、找到 File -> Settings -> Editor -> File and Code Templates -> Includes,编辑FileHeader模板如下:

/**
* <h3>${PROJECT_NAME}</h3>
* @description
* <p>${description}</p>
* @author panziye
* @date ${YEAR}-${MONTH}-${DAY} ${HOUR}:${MINUTE}
**/
提示:可以依据自己的需求与规则进行设置

具体说明如图:
Intellij IDEA新建类自动生成JavaDoc注释,一键生成文档

注意:这里的模板默认对所有新建的java相关文件(如下图)都有效,因为它们都引用了FileHeader.java,因此你也可以针对类或接口等做特别的模板定制

Intellij IDEA新建类自动生成JavaDoc注释,一键生成文档
3、我们在TestDemo1项目中新建Class(我在此将类命名为TestDoc,放在包)会发现多了一步输入描述:
Intellij IDEA新建类自动生成JavaDoc注释,一键生成文档
4、创建成功后,其结构如下(我加了main方法):
Intellij IDEA新建类自动生成JavaDoc注释,一键生成文档

2、一键生成JavaDoc

1、打开Tools -> Generate JavaDoc配置如下:
Intellij IDEA新建类自动生成JavaDoc注释,一键生成文档

-tag date:a:日期 -tag description:a:描述 -encoding UTF-8 -charset UTF-8
注意:如果有自定义的javadoc标签,则需要在other command line arguments框中输入定义,例如:-tag date:a:日期 -tag description:a:描述 -encoding UTF-8 -charset UTF-8 来指定未定义的注解及指定文档编码为UTF-8,否则可能会报错

2、生成后文档如下:
Intellij IDEA新建类自动生成JavaDoc注释,一键生成文档

3、双击index.html浏览器打开
(忽略包名,格式写错了)
Intellij IDEA新建类自动生成JavaDoc注释,一键生成文档
点开类:
Intellij IDEA新建类自动生成JavaDoc注释,一键生成文档

3、JavaDoc插件

其实我们还可以使用JavaDoc插件帮助我们有效地管理JavaDoc文档,应该支持到对应得方法、形参、返回值等等注解模板的自动生成,不过我这里由于IDEA版本太低,安装失败,有兴趣的可以去Settings -> Plugins中安装使用,在此不再赘述。
Intellij IDEA新建类自动生成JavaDoc注释,一键生成文档

4、补充说明

常用JavaDoc注解:

Intellij IDEA新建类自动生成JavaDoc注释,一键生成文档

阿里巴巴JavaDoc约束规则:

阿里巴巴Java开发手册之注释规约:

类,类属性、类方法的注释必须使用Javadoc规范,使用/*内容/格式,不得使用//XX方式。

所有的抽象方法(包括接口中的方法)必须要用Javadoc注释,除了返回值、参数、异常说明外,还必须指出该方法做什么事情,实现什么功能。

所有的类都必须添加创建者和创建日期。

方法内部的单行注释,在被注释语句上方另起一行,使用//注释。方法内部的多行注释,使用/* */注释,注意与代码对齐。

所有的枚举类型字段必须要有注释,说明每个数据项的用途。

与其用不熟练的英文来注释,不如用中文注释把问题说清楚。专有名词与关键字保持英文原文即可。

在修改代码的同时,要对注释进行相应的修改,尤其是参数,返回值,异常,核心逻辑等的修改。

谨慎注释掉代码。要在上方详细说明,而不是简单的注释掉。如果无用,则删除。

对于注释的要求:

(1)能够准确反映设计思想和代码逻辑。

(2)能够描述业务含义,使其他程序员能够迅速了解代码背后的信息。完全没有注释的大段代码对于阅读者形同天书;注释是给自己看的,应做到即使间隔很长时间,也能清晰理解当时的思路,注释也是给继任者看的,使其能够快速接替自己的工作。

好的命名、代码结构是自解释的,注释力求精简准确、表达到位。避免出现注释的一个极端:过多过滥的注释,因为代码的逻辑一旦修改,修改注释是相当大的负担。

特殊注释标记,请标明标记人与标记时间。注意及时处理这些标记,通过标记扫描经常处理此类标记。有时候线上故障就来源于这些标记处的代码。


版权声明:本站文章,如无说明,均为本站原创,转载请注明文章来源。如有侵权,请联系博主删除。
本文链接:https://www.panziye.com/java/2494.html
喜欢 (3)
请潘老师喝杯Coffee吧!】
分享 (0)
用户头像
发表我的评论
取消评论
表情 贴图 签到 代码

Hi,您需要填写昵称和邮箱!

  • 昵称【必填】
  • 邮箱【必填】
  • 网址【可选】