部门A采用ReactNative开发，维护RN组件库，部门B采用原生开发。为了应对业务的快速迭代，B部门的学生也需要访问RN。所以就有了以下问题。
B 部门同学想要知道：
A 组件库支持什么功能
A 组件库的组件怎么使用
A 部门组件库存在的问题：
没有文档说明（曾经有，迭代太快，写文档太麻烦，久而久之就过时了）
注释较少，时间久了，原开发同学都离职了，想要搞清楚组件支持的功能得扒源码看
A需要经常支持B，这很麻烦，不想花太多时间写文档。为了解决这个问题，我参考了原生开发使用的Javadoc工具，最后找到了这个-typedoc。使用后体验还可以，比每次选择源代码都方便。写一篇文章来分享这个工具。
TypeDoc 将 TypeScript 源代码中的注释转换为呈现的 HTML 文档或 JSON 模型。它是可扩展的，支持多种配置。
初始化工程
创建一个新的 TS React 应用来演示功能
npm install -g create-react-appcreate-react-app type-doc-demo --template typescript
安装typeDoc
npm install typedoc --save-dev工程说明
组件工程的目录结构如下所示
.├── components│ ├── Card│ │ └── index.tsx│ ├── Filter│ │ └── index.tsx│ └── index.tsx├── demo│ └── Filter.tsx├── App.tsx...
components/index.tsx导出所有组件，demo目录包含示例代码。
// components/index.tsxexport { Card } from "./Card";export type { CardProps } from "./Card";export { Filter } from "./Filter";export type { FilterProps } from "./Filter";
基础功能
在项目根目录创建typedoc.js文件，指定入口文件和输出目录
// typedoc.jsmodule.exports = {entryPoints: ["./src/components/index.tsx"],out: "doc",name: "组件库",};
package.json添加脚本打包看看效果
// package.json..."scripts": {"doc": "typedoc --tsconfig tsconfig.json --options typedoc.js"},...
执行 npm run doc，效果如下，默认会将README.md内容放在首页
MarkDown语法
typeDoc将通过导出内容的注释生成文档，注释支持MarkDown语法，所以可以将注释这么写
插入表格
export type FilterProps = {/*** 弹窗类型** |drop|fullscreen|* |:---:|:---:|* |下拉| 全屏|* */modalMode?: "dorp" | "fullscreen";};
插入示例代码
export type FilterProps = {/*** 配置* ```* {* base_filter: {* checkBox: {* columns: 4,* },* },* }*```*/config?: object;};
生成文档效果
插入自定义资源
typedoc.js增加如下配置
// typedoc.jsmodule.exports = {...media: ["./demo-images"],includes: ["./src/demo"],};
includes: 包含文件的目录，这些文件可以[[include:file.md]]在文档注释中注入到生成的文档中。
media：指定将复制到输出文件的媒体目录。媒体可以media://file.jpg在文档注释中链接到
添加上述配置后，在注释中就可以通过如下方式访问对应资源了
/*** # 筛选器* ## 示例图* <img src="media://Filter.jpg" width="50%" />** @see [数据格式说明文档](https://www.baidu.com)** ## 代码示例* ### 使用* ```* [[include:Filter.tsx]]* ```**/export const Filter: React.FC<FilterProps> = () => {...};
生成文档效果如下
综上，便以较小的工作量生成了一个简单的开发文档，提供了代码示例、功能示例图、属性说明，如果只供内部使用的话还比较方便。
其他配置
配置文件
可以在typedoc.js文件中填下如下配置
module.exports = {excludePrivate: true, // 导出不包含private声明内容excludeProtected: true, // 导出不包含protected声明内容// 将包版本添加到项目名称中。在这种情况下，如果项目是根据 1.2.3 版本`package.json`，这将生成名为“名称 - v1.2.3”的文档includeVersion: true,};
注释标签
@ignore：文档忽略该模块
@category：将该内容分组，同标签会划分一起
原文作者：IT枫斗者；如有侵权，请联系管理员删除。
