java开发文档 javaapi文档 收藏 0

java 文档自动生成的神器 idoc

作为一名开发者，每个人都要写代码。

工作中，几乎每一位开发者都要写文档。

因为工作是人和人的协作，产品要写需求文档，开发要写详细设计文档，接口文档。

可是，作为一个懒人，平时最讨厌的一件事情就是写文档。

写文档最令我不爽的地方是在于代码备注要改一遍，然后文档再改一遍。

所有重复的劳作，都是对于我们宝贵摸鱼时间的最大浪费。

于是，我就常常想，能不能只写一遍呢？

idoc[1] 为 java 项目生成项目文档。

基于原生的 java 注释，尽可能的生成简介的文档。用户可以自定义自己的模板，生成自己需要的文档。

实现原理：基于 maven 插件，类似于 javadoc。可以更加灵活，允许用户自定义。

（1）基于 maven 项目生成包含大部分信息的元数据

（2）默认支持 markdown 简化文档的生成，支持自定义模板

（3）支持用户自定义文档生成器

（4）支持用户自定生成文档的类过滤器

（5）添加字段类型别名，支持用户自定义

jdk1.8+

maven 3.x+

使用 maven 引入当前 idoc 插件。

为了演示文档，我们创建了一个 Address 对象。

当然，你可以发现这里只是把元数据进行输出到控台，意义不大。

我们可以根据需求，自定义实现生成类。

比如下面的方式，可以使用内置的 MarkdownDocGenerator 输出到 markdown 文件。

效果可以参考：

heaven 文档目录[2]

ps: heaven[3] 项目是个人整理了多年的工具包，几百个类，手写文档估计要很久。

Java 文档一直是一个大问题。

很多项目不写文档，即使写文档，对于开发人员来说也是非常痛苦的。

不写文档的缺点自不用多少，手动写文档的缺点也显而易见：

1.

非常浪费时间，而且会出错。

2.

无法保证及时更新。代码已经变了，但是文档还要同步修改。需要强制人来维护这一种一致性。这很难。

java 的文档有几类：

1.jdk 自带的 doc 生成。这个以前实践给别人用过，别人用 C#，看到 java 的默认文档感觉很痛苦。

就算是我们 java 开发者，也很讨厌看 jdk 的文档。看着不美观，也很累。

1.swagger-ui 是基于 java 注解的文档生成工具。相对而言比较优雅，也非常强大。

但是缺点也是有的。开发人员要写 jdk 原来的注释+注解。注解太多，导致写起来也很痛苦，大部分开发者后来还是选择了放弃。

那么问题来了？我们怎么办才能尽可能的让开发人员，和文档阅读人员都乐于接受呢？

jdk 自带的 doc 就是基于 maven 插件的，本项目也是。

区别如下：

1.

尽可能的保证和 Java 原生注释一致，让开发者很容易就可以使用。

2.

尽可能的信息全面，但是文档简洁。让文档的阅读者享受到等同于手写文档的体验。

3.

将信息的获取和生成区分开。方便用户自己定义自己的输出方式。

为了更加灵活的实现文档的生成和文档元数据的生成，提供如下参数

简单的文档，建议直接生成在一个文件。

如果较为复杂，则可以设为 false，则会按照

默认的命令行文档，主要用于演示和信息查看，不具有实际意义。

建议引入 idoc-ftl 模块，使用 MarkdownDocGenerator 生成器。

可以同时指定多个。

可引入 idoc-api 自行定义。

实际的文档，主要关心定义的方法。

我们可以针对 DocClass 的包名，过滤只生成 Service 方法文档。

如果是在以前的基础上，则可以加上 @since @version 等信息的过滤。

可以同时指定多个。

可引入 idoc-api 自行定义。

可以参考当前项目的 idoc-test 模块。

整体配置如下:

指定使用 Markdown 文档生成器，可以同时指定多个。

MarkdownDocGenerator 在 idoc-ftl 模块中，需要引入对应的依赖。

当然 idoc-core 默认依赖 idoc-ftl。

如果不定义自己的类生成过滤器，则会生成所有的类信息。

一般使用中我们只关心 service 方法，所以添加了类的过滤实现。

实现如下：

注意，也需要将你定义这个过滤器的 jar 添加依赖，否则无法找到对应的类信息。

@require 表示当前字段是否必填，作为方法入参时。

@remark 表示当前字段的备注信息。

•QueryUserService.java

•日志信息

当前文件路径日志会打印，比如我自己测试的为：

/Users/houbinbin/code/_github/idoc/idoc-test/src/main/resources/idoc-gen/idoc-test-全部文档.md

参见文档:

idoc-test-全部文档.md[4]

可以参考当前项目的 idoc-test 模块。

有时候页面显示类型，希望更加友好。

所以系统内置了一些别名显示，也同时支持自定义别名。

系统当前版本提供了常见的别名。

详情见 com.github.houbb.idoc.core.util.JavaTypeAliasUtil

可以通过 typeAlias 指定自定义的字段别称。

用户自定义的字段别名优先级高于系统默认。

后面定义的别名会直接覆盖前面的别名。

运行测试日志如下：

其中 typeAlias 就是字段类型的别名，我们可以用来更加友好的显示字段信息。

自定义的方式采用基于 xml 的方式是比较方便。

但是数量比较多的时候就没有那么方便，本来考虑添加对应的配置属性接口，权衡下还是使用了 xml 配置的方式。

如果一个字段，没有指定别名，是否使用 comment 信息做替代？

建议使用，当前版本不做处理。

•为什么使用

比起冗长的类信息，大部分人更乐于看到解释。

如果是针对同构的系统(都是 java 语言)，则可以理解。

如果是针对异构的系统(比如前台是 php)，则不易于理解。

•为什么不处理

大部分的接口都是常见字段, 性价比不高。

可能存在字段没有些 comment 的情况，会导致判断的复杂性。

直接修改模板即可，使用原来的字段 type 属性即可。

https://github.com/houbb/idoc

当然，这个项目还有很长的路要走。

如果喜欢，欢迎 fork star~

[1] idoc: https://github.com/houbb/idoc[2] heaven 文档目录: https://github.com/houbb/heaven/blob/master/doc/gen/heaven-%E7%B4%A2%E5%BC%95.md[3] heaven: https://github.com/houbb/heaven[4] idoc-test-全部文档.md: doc/blog/demo/idoc-test-全部文档.md

2022最新版阿里Java开发手册发布！「附PDF下载」

哈喽大家好啊，今天Hydra要给大家分享一份实用的《Java 开发手册-黄山版》，读过往年版本这本小册子的小伙伴们应该熟悉，它是阿里巴巴集团技术团队的集体智慧结晶和经验总结。经历了多次大规模一线实战的检验及不断完善，公开到业界后，众多社区开发者踊跃参与，共同打磨完善，系统化地整理成册。

在前不久，终于发布了2022年最新版本的『黄山版』，大家可以来先一睹为快！

获取完整PDF内容：请转发、点赞，关注头条号后私信 “黄山” 向小编索取。

大家可以先预览一下目录，总共分为七大模块，以及一些附加信息。

下面带领大家，先来分章节预览一下各个部分的内容，对这本小册子有一个大致的了解。

2、异常日志

3、单元测试

4、安全规约

5、MySQL数据库

6、工程结构

7、设计规约

其他的内容还有很多，这里就不再一一描述了，有兴趣的小伙伴们可以自己下载这本电子书来看一下。

获取完整PDF内容：请转发、点赞，关注头条号后私信 “黄山” 向小编索取。

本文作者及来源:Renderbus瑞云渲染农场https://www.renderbus.com