DOC文档注释,让你的代码如此清晰。

1.开发背景

最近一直在写dubbo接口,以前总是用word文档写接口描述然后发给别人。现在太多了,而且跟别人对接联调的人家急着用,根本没时间去写word文档。那就想想怎么用doc文档注释自动生成接口文档了。本来以前对这一块有点印象,但是并不熟悉,加上没有很强烈的要去使用的意图,所以一直没有弄。今天要感谢公司的大神,大家都叫他欧神,神一样的男人。让我用文档注释。然后就知道怎么弄了,以下是生成的流程。

2.生成方法

先说生成的方法吧,免得一开始将注释规范可能读者觉得比较繁琐,而且注释规范基本上大家都有一套自己的做法。只要规范了注释,就能轻易的生成注释文档。

2.1单击project->Generate Javadoc出现如下界面

Javadoc command:执行doc文档注释的命令,也可以在cmd窗口中输入这个命令

Select types for which Javadoc will be generated:要生成文档注释的项目,这里选择dubbo中间价项目,接口都在这里面声明,生成的文档自然就够用了

Create Javadov for menbers with cisibility:选择private就将私有属性也生成到文档中,默认选择的是public,建议选择private

Destination:生成文档路径

2.2点击下一步

这一页的配置基本上全部选择默认,也可以根据自己的尿性勾选必要的东西

这里也可以导入自己的样式文件,这样可以让文档更美观,这里省略

文档标题可以使用html,示例如下:

大数据接口Api

<h2><ul><li>Maven:</li><li>&lt;dependency&gt;</li><li>&nbsp;&nbsp;&lt;groupId&gt;api.jjshome.bigdata&lt;/groupId&gt;</li><li>&nbsp;&nbsp;&lt;artifactId&gt;bd-api-client&lt;/artifactId&gt;</li><li>&nbsp;&nbsp;&lt;version&gt;1.0.0-SNAPSHOT&lt;/version&gt;</li><li>&lt;/dependency&gt;</li></ul></h2>

2.3点击下一步

这里要输入自定义@标签的定义,如下:

-encoding UTF-8 -charset UTF-8 -tag 功能描述\::a:"功能描述" -tag 项目名称\::a:"项目名称" -tag 项目版本\::a:"项目版本" -tag 使用对象\::a:"使用对象" -tag 接口版本\::a:"接口版本" -tag 创建作者\::a:"创建作者" -tag 创建日期\::a:"创建日期" -tag 问题反馈\::a:"问题反馈";

当然了,如果你全部用doc自带的标签就不用输入任何东西了。

2.4点击完成

然后去2.1步骤中生成的doc路径下打开index.html就可以看到doc文档了,成果如下:

到这里就完成了生成的步骤了,下面我说一下一点点注释要注意的地方,对于注释规范的人可以不用看下去了,但是如果你生成的api里面基本上没有什么内容,那么建议你还是看看下面的内容。

3.doc注释

3.1多行注释

对于属性,方法,类的注释必须使用多行注释,单行注释不会生成到文档中

3.2属性注释:

/** 员工ID */

private String workerId;

3.3方法注释:

/**

* @功能描述: <p>根据workerId查询经纪人小区带看列表</p>

* <p><font color=red>注意:</font>

* 只返回根据带看数量,最近一次带看时间倒序排序的前topNum条记录</p>

* @创建作者: **

* @创建日期: 2016年9月22日 下午3:11:46

* @param workerId 员工ID

* @param topNum 排序前几个

* @return <p>返回对象参考{@link BigdataResult}<{@link List}<{@link AgentDKRecordVo}>></p>

*/

public BigdataResult<List<AgentDKRecordVo>> queryAgentDKList(String workerId, Integer topNum);

这里多使用注解就能生成漂亮的文档了,参数和返回对象一定要写清楚,如果有对象参数的话,就可以用@see注解,示例如下:

/**

* @功能描述: 根据workerId查询经纪人成交记录

* @创建作者: **

* @创建日期: 2016年9月22日 下午8:49:02

* @param workerId 员工ID

* @param page 分页对象

* @return <p>返回对象参考{@link BigdataResult}<{@link List}<{@link EsfCjHqHouseInfo}>></p>

* @see PageInfo

*/

public BigdataResult<List<EsfCjHqHouseInfo>> queryEsfCjListByWorkerId(String workerId, PageInfo page);

这里的@see和@link都可以链接到指定对象的注释文档页面,具体区别使用一次之后就一目了然了,同时@see和@link后面的对象也是需要导包的,不导包的话就使用全局限定名,如@see java.util.List

当然,还可以加入自己定义的一些注解,这些注解要生成到文档注释中就要在如上图的2.3步骤中声明出来,如@功能描述

3.4类的注释

/**

* @功能描述: 接口返回错误码

* @项目版本: 1.0.0

* @项目名称: 大数据接口中心

* @相对路径: *.ResultCodeCenter.java

* @创建作者: **

* @问题反馈: **@126.com

* @创建日期: 2016年9月22日 下午2:32:53

*/

public class ResultCodeConstant {}

4注释模板

单击window->Preferences,搜索框输入“Template”,就能看到模板设置的选项了,举个栗子:

这里可以对属性,方法,类,以及更多内容做模板设置,这样输入注释的时候就能统一了,而且免去了多打字的痛苦,上图是一个类的注释模板

有了这些基本上生成的接口文档就够用了,当然。如果有更高的要求或者注释有自己的规范,也可以按照自己的来设置更多内容。

原文发布于微信公众号 - java工会(javagonghui)

原文发表时间:2018-05-12

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

发表于

我来说两句

0 条评论
登录 后参与评论

相关文章

来自专栏Python

IO模型

一 概念理解 在进行网络编程时,我们常常见到同步(Sync)/异步(Async),阻塞(Block)/非阻塞(Unblock)四种调用方式: 同步:   所谓同...

1875
来自专栏闻道于事

Linux简介,虚拟机安装,网络设置,桌面和vim安装

Linux简介: linux代表系统内核。 Linux系统指基于Linux内核的操作系统,由内核和程序结合组成。 比较流行的发行版本由RedHat Linux、...

3616
来自专栏信安之路

记一次审计 xiaocms 的过程

周末在家刚吃完晚饭,基友 DM 叫我一起来审计 xiaocms 系统,也不知道他是受到啥刺激了。正好,除了 Code Review 公司项目代码及框架代码,未审...

5260
来自专栏PHP在线

PHP并发IO编程之路

原文出处: 韩天峰(@韩天峰-Rango) 并 发IO问题一直是后端编程中的技术挑战,从最早的同步阻塞Fork进程,到多进程/多线程,到现在的异步IO、协程。...

5367
来自专栏崔庆才的专栏

RESTful API 设计最佳实践

原文出处:RESTful API Design. Best Practices in a Nutshell. 原文:RESTful A...

3706
来自专栏木可大大

漫谈进程和线程

我们知道文件是对I/O设备的抽象,虚拟存储器是对文件和主存的抽象,指令集是对CPU的抽象,进程是对指令集和虚拟存储器的抽象。如下图所示 。

1.3K5
来自专栏黑泽君的专栏

day69_淘淘商城项目_02

  由于淘淘商城是基于soa的架构,表现层和服务层是不同的工程。所以要实现商品列表查询需要两个系统之间进行通信。   如何实现远程通信?

2002
来自专栏美团技术团队

Android远程调试的探索与实现

作为移动开发者,最头疼的莫过于遇到产品上线以后出现了bug,但是本地开发环境又无法复现的情况。常见的调查线上棘手问题方式大概如下: ? 以上两种方法在之前调查线...

5023
来自专栏编程

2018 年了,你还是只会 npm install 吗?

你真的了解 npm 吗 ?重新介绍 npm 。

3.4K16
来自专栏程序员互动联盟

【入门必备】编程必备技能--抓出代码中的蛀虫

很多的朋友,在写代码的时候经常运行出错然而却找不到哪里错了。那就是你没有学会分析错误,你到底错在哪里了?为什么错了? 第一种代码致命错误。 一般的错误代码在编译...

2786

扫码关注云+社区