核心思想

数据 + 模板 = 视图

将文档元数据的获取和生成分离。

i-doc 希望达到的目标

对开发者的友好

手写文档的缺点自不用说。

以前也接触过类似 swagger-ui 等基于注解的文档生成工具，但使用起来终究不尽如人意。

基于注解的文档工具，让代码的可读性反而下降。

简洁性

java-doc 生成的文档又过于复杂。

实际使用中希望可以足够简介，比如不同系统之间的文档对接。

灵活性

作为工具，永远不知道使用者需要怎样的信息。

所以分成两大块。

元数据的生成，包含基本所有的文档信息。

文档的生成，提供默认的实现。用户可以基于模板灵活配置，也可以自行实现。

项目模块概览

idoc-api

定义用户使用的 api，提供最基础的接口和元数据。

便于用户在此基础上进行自定义开发，如指定生成文件的过滤方式。

idoc-common

当前项目的基础模块，提供基础的工具方法。

用户也可以引入此模块，进行自己的文档生成实现。

idoc-core

本插件的核心功能，主要负责将 java 文档的元数据信息整理出来，并提供核心的文档生成架构。

idoc-ftl

基于 Freemarker 模板的文档生成，支持其所有语法。

现在主要用于生成 markdown 文档。

用于可以自定义自己的模板，生成更适合自己的 markdown 文档。

idoc-poi

基于 Apache poi 生成 word、pdf 等类型的文档。

0.0.X 版本暂时不引入，后续版本会实现。

idoc-test

测试模块。

一些使用案例可以参考这个模块，同时也为项目的质量提供一定的保证。

项目的格局

语言

后期希望支持 i18n，而不是拘泥于中文项目。

针对性

针对用户的自定义类型，而不是和 java-doc 做重复的事情。