java idoc_java 自动生成代码文档框架 idoc 项目模块说明.docx

i-doc 项目简介

idoc 是为 java 项目生成项目文档。

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

特性

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

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

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

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

核心思想

数据 + 模板 = 视图

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

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 做重复的事情。