部門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-app
create-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.tsx
export { Card } from "./Card";
export type { CardProps } from "./Card";
export { Filter } from "./Filter";
export type { FilterProps } from "./Filter"; 基礎功能
在項目根目錄建立typedoc.js檔案，指定入口檔案和輸出目錄
// typedoc.js
module.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.js
module.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：将該内容分組，同标簽會劃分一起