自动生成 java markdown 文档生成框架-01-入门使用

谁借莪１个温暖的怀抱￠ 2022-03-06 11:50 806阅读 0赞

# 设计初衷 #

## 节约时间 ##

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

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

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

1.  非常浪费时间，而且会出错。
2.  无法保证及时更新。代码已经变了，但是文档还要同步修改。需要强制人来维护这一种一致性。这很难。

## 为什么不是 swagger-ui ##

java 的文档有几类：

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

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

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

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

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

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

区别如下：

1.  尽可能的保证和 Java 原生注释一致，让开发者很容易就可以使用。
2.  尽可能的信息全面，但是文档简洁。让文档的阅读者享受到等同于手写文档的体验。
3.  将信息的获取和生成区分开。方便用户自己定义自己的输出方式。

# IDOC #

# i-doc 项目简介 #

为 java 项目生成项目文档。

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

## 特性 ##

*  基于 maven 项目生成包含大部分信息的元数据
 *  默认支持 markdown 简化文档的生成，支持自定义模板
 *  支持用户自定义文档生成器
 *  支持用户自定生成文档的类过滤器

## 新特性 ##

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

# 快速入门 #

## 需要 ##

jdk1.8+

maven 3.x+

## maven 引入 ##

使用 maven 引入当前 idoc 插件。

<build>
        <plugins>
            <plugin>
                <groupId>com.github.houbb</groupId>
                <artifactId>idoc-core</artifactId>
                <version>0.1.0</version>
            </plugin>
        </plugins>
    </build>

## 测试对象的创建 ##

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

package com.github.houbb.idoc.test.model;
    
    /** * 地址 * @author binbin.hou * @since 0.0.1 */
    public class Address { 
    
        /** * 城市 */
        private String country;
    
        /** * 街道 */
        private String street;
    
        public String getCountry() { 
            return country;
        }
    
        public void setCountry(String country) { 
            this.country = country;
        }
    
        public String getStreet() { 
            return street;
        }
    
        public void setStreet(String street) { 
            this.street = street;
        }
    }

## 执行插件 ##

mvn com.github.houbb:idoc-core:0.0.2:idoc

## 命令行日志信息 ##

[INFO] ------------------------------------ Start generate doc
    [INFO] 共计 【1】 个文件待处理，请耐心等待。进度如下：
    ==================================================================================================== 100%
    [INFO] Generator doc with docGenerator: com.github.houbb.idoc.core.api.generator.ConsoleDocGenerator
    [INFO] ------------------------------------ 文档信息如下：
    
    [类名] com.github.houbb.idoc.test.model.Address
    [类信息] {"comment":"地址","docAnnotationList":[],"docFieldList":[{"comment":"城市","name":"country","type":"java.lang.String"},{"comment":"街道","name":"street","type":"java.lang.String"}],"docMethodList":[{"docMethodParameterList":[],"docMethodReturn":{"fullName":"java.lang.String","name":"String","packageName":"java.lang"},"docTagList":[],"exceptionList":[],"modifiers":["public"],"name":"getCountry","seeList":[],"signature":"getCountry()"},{"docMethodParameterList":[{"docAnnotationList":[],"name":"country","type":"java.lang.String"}],"docMethodReturn":{},"docTagList":[],"exceptionList":[],"modifiers":["public"],"name":"setCountry","seeList":[],"signature":"setCountry(country)"},{"docMethodParameterList":[],"docMethodReturn":{"fullName":"java.lang.String","name":"String","packageName":"java.lang"},"docTagList":[],"exceptionList":[],"modifiers":["public"],"name":"getStreet","seeList":[],"signature":"getStreet()"},{"docMethodParameterList":[{"docAnnotationList":[],"name":"street","type":"java.lang.String"}],"docMethodReturn":{},"docTagList":[],"exceptionList":[],"modifiers":["public"],"name":"setStreet","seeList":[],"signature":"setStreet(street)"}],"docTagList":[{"lineNum":5,"name":"author","parameters":["binbin.hou"],"value":"binbin.hou"},{"lineNum":6,"name":"since","parameters":["0.0.1"],"value":"0.0.1"}],"fullName":"com.github.houbb.idoc.test.model.Address","modifiers":["public"],"name":"Address","packageName":"com.github.houbb.idoc.test.model"}
    
    [INFO] ------------------------------------ Finish generate doc

# Markdown 的生成 #

参考 [03-自定义生成文件过滤器][03-]

效果参见 [idoc-test-全部文档.md][idoc-test-_.md]

# 进一步学习 #

[00-项目概览][00-]

[01-设计初衷][01-]

[02-插件的参数配置][02-]

[03-自定义生成文件过滤器][03-]

[04-字段类型别名支持][04-]

[03-]: https://github.com/houbb/idoc/blob/release_0.1.0/doc/blog/%E6%96%87%E6%A1%A3%E7%94%9F%E6%88%90-03-%E8%87%AA%E5%AE%9A%E4%B9%89%E7%94%9F%E6%88%90%E6%96%87%E4%BB%B6%E8%BF%87%E6%BB%A4%E5%99%A8.md
[idoc-test-_.md]: https://github.com/houbb/idoc/blob/release_0.1.0/doc/blog/demo/idoc-test-%E5%85%A8%E9%83%A8%E6%96%87%E6%A1%A3.md
[00-]: https://github.com/houbb/idoc/blob/release_0.1.0/doc/blog/%E6%96%87%E6%A1%A3%E7%94%9F%E6%88%90-00-%E9%A1%B9%E7%9B%AE%E6%A6%82%E8%A7%88.md
[01-]: https://github.com/houbb/idoc/blob/release_0.1.0/doc/blog/%E6%96%87%E6%A1%A3%E7%94%9F%E6%88%90-01-%E8%AE%BE%E8%AE%A1%E5%88%9D%E8%A1%B7.md
[02-]: https://github.com/houbb/idoc/blob/release_0.1.0/doc/blog/%E6%96%87%E6%A1%A3%E7%94%9F%E6%88%90-02-%E6%8F%92%E4%BB%B6%E7%9A%84%E5%8F%82%E6%95%B0%E9%85%8D%E7%BD%AE.md
[04-]: https://github.com/houbb/idoc/blob/release_0.1.0/doc/blog/%E6%96%87%E6%A1%A3%E7%94%9F%E6%88%90-04-%E5%AD%97%E6%AE%B5%E7%B1%BB%E5%9E%8B%E5%88%AB%E5%90%8D%E6%94%AF%E6%8C%81.md