# Doc-4-Type

🎉 本项目已发布 beta 版，欢迎试用 (opens new window)

根据 TypeScript 类型+代码注释自动生成代码文档的工具。支持生成的文档类型包括 markdown, html, 以及 json。

与 markdown 静态页面生成器(e.g. vuepress (opens new window))搭配使用，可以实现类型文档自动化。

本文档也是工具搭配文档生成器VuePress使用的例子，可以查看 docs (opens new window) 中的示例。

# Type as Doc / 类型即文档

江湖中有一句话叫"类型是最好的注释"。例如以下类型，不看任何注释，我们也可以清晰明了地知道这个图形绘制配置项对象大概怎么使用。

/** 绘制一个基本图形 */
type Shape {
  /** 椭圆还是矩形 */
  type: 'circle' | 'square',
}

更进一步，我们希望可以做到通过类型直接生成文档，免去耗时的手工文档工作。搭配一些页面生成器就能轻易生成主页。

# Shape

* type: `object`
* 描述: 绘制一个基本图形

## type

* type: `'circle' | 'square'`
* 描述: 椭圆还是矩形

这就是本项目的基本愿景。

# Background

Inspired and builds upon typescript-json-schema (opens new window).

# QuickStart

假设我们的目录结构:

.
├── package-lock.json
├── package.json
└── src
    ├── main.js
    └── type.ts <- 想要生成文档的类型文件

其中，type.ts 中定义了一个类型 MyObject:

interface Type1 {
  value1: string;
  value2: number;
}
interface Type2 {
  value2: number;
  value3: boolean;
}

interface MyObject {
  value: Type1 & Type2;
}

本工具有两种方式可供使用: JS API 或 CLI。功能完整度相同，都会生成一样的 markdown 文档。

# JS API

$ npm i doc-for-type

// main.js
const { doc4Type } = require("doc-for-type");
const { join } = require("path");

doc4Type({
  input: join(__dirname, "./type.ts"),
  typeName: "MyObject",
  format: 'markdown',
});

$ node src/main.js

# CLI

$ npm i doc-for-type -g
$ doc4type --input ./src/type.ts --typeName MyObject

# 了解详细使用方法

请查看我们的JS API 文档。以及注释 API 文档

# TIP

推荐多使用 Interface，这样可以在编译解析时保留接口名称，而 Type 会被丢弃。

# 已知问题

~~对递归类型的支持 8 行~~ 现在行了，做了环检测
不展示 index type 的细节类型，只展示 object。因为暂时没想好怎么在文档里表现，有建议可以帮我提个 issue。