TypeScript 如何做类型文档

你写代码的时候，有没有过这种经历：刚写好的函数，过了一个月自己都忘了参数要传什么类型；同事接手你写的代码，翻遍整个文件才搞懂某个变量的用途？要是有TypeScript，这些麻烦能少一半，而且它还能帮你生成清晰的类型文档，不管是给自己看还是给别人用都省心。

先搞懂：TypeScript的类型文档到底是什么？

简单说，它就是给代码“贴说明标签”。比如你写了一个计算商品总价的函数，只写function calcTotal(price, count)，别人不知道price是单价、count是数量，甚至会不会传负数。但如果把参数类型写上function calcTotal(price: number, count: number): number，还加上注释，这就是最基础的类型文档了。它不用像Word文档那样专门写一大段，而是和代码绑在一起，改代码的时候文档自动更新，不会出现“代码改了，说明还没更”的尴尬。

最常用的3种类型文档写法，普通人也能上手

不用记复杂的命令，这几种日常用足够，跟着例子学就行。

第一种，也是最基础的，就是直接在代码里写类型注解。比如你写了一个给用户发消息的函数，直接给参数和返回值加类型，还可以加中文注释说明用途：

`typescript

// 计算用户下单时的总运费，重量超过5kg需加价2元

function calcShippingFee(weight: number, isMember: boolean): number {

let fee = weight * 3; // 基础运费3元/kg

if (weight > 5) fee += 2; // 超重加价

if (isMember) fee *= 0.9; // 会员打9折

return fee;

}

`

你看，别人拿到这段代码，一眼就知道每个参数要传什么，函数做什么，完全不用额外问。

第二种，用JSDoc给复杂类型加说明。要是遇到对象或者自定义类型，直接写注解更清楚。比如你做了一个电商的商品类型，用JSDoc给每个字段加注释：

`typescript

/**

• 电商商品的核心信息
• @property {string} id - 商品唯一编号，格式为P+6位数字（如P001234）
• @property {string} name - 商品名称，最多20个汉字
• @property {number} price - 商品售价，单位为元，保留两位小数
• @property {'上架'|'下架'|'预售'} status - 商品状态，只能传这三个值

*/

type Product = {

id: string;

name: string;

price: number;

status: '上架'|'下架'|'预售';

};

`

这里的status是固定的几个状态，用联合类型加JSDoc注释，别人不会传错值，比只写status: string要靠谱太多。

第三种，一键生成完整的HTML文档。要是你写的是给团队用的工具库，不可能让大家都蹲在代码里看注解，这时候可以用TypeDoc这个小工具。它会自动扫描你代码里的类型注解、JSDoc注释，生成带目录的HTML页面，打开就能搜函数、查类型，和官方的API文档一模一样。比如你装完TypeDoc，只需要在命令行敲一行typedoc --out docs src，它就会把你src文件夹里的所有代码，转成一个叫docs的文件夹，打开里面的index.html就是完整的类型文档。

写类型文档的小技巧，少踩坑

别写没用的注释，比如// 定义用户类型这种等于没写，要写“这个字段是干嘛的、能传什么值、有什么规则”。比如刚才的商品id，写// 商品唯一编号就比只写// 商品id有用。另外，要是用了联合类型，一定要把所有允许的值都列出来，别让同事猜，比如状态就写死三个值，别只写// 商品状态。

其实TypeScript的类型文档，本质就是把“代码的使用说明”写在代码里，不用额外整理，改代码的时候顺便更了，不管是自己后续维护，还是团队协作，都能省超多时间。哪怕是刚学TypeScript的新手，把这几种方法用熟，就能解决大部分类型文档的需求，不用一开始就啃复杂的配置。