typescript为javascript添加静态类型，有助于尽早发现错误并简化大型代码库的管理。但全面迁移到typescript有时难度很大。这时，jsdoc就派上用场了，它允许您在不进行全面重构的情况下，获得静态类型系统的大部分优势。
JSDoc的强大之处在于它不仅仅是代码注释。通过@typedef和@type，您可以在JavaScript文件中创建可复用的复杂类型定义，从而提升代码的可读性和安全性，而无需TypeScript的复杂配置。
JSDoc的适用场景：
- 小型项目: 对于小型项目，完整的TypeScript配置可能显得过于繁重。JSDoc提供了一种轻量级的添加类型和文档的方法。
- 逐步迁移: JSDoc可以作为迁移到TypeScript的桥梁。您可以先从JSDoc开始，生成声明文件，然后逐步过渡到完整的TypeScript。
- 已有JavaScript代码库: 将大型JavaScript代码库迁移到TypeScript可能非常耗时。JSDoc允许您逐步引入类型，无需一次性重写所有代码。
- 文档优先: JSDoc强调代码文档，这无论您使用哪种类型系统都是至关重要的。良好的文档始终是代码库的加分项。
使用@typedef和@type定义类型:
以下是如何使用JSDoc定义类型的示例：
立即学习“Java免费学习笔记（深入）”；
/**
* @typedef {object} Point
* @property {number} x - x坐标.
* @property {number} y - y坐标.
*/
/**
* 计算两点之间的距离.
* @param {Point} p1 - 第一个点.
* @param {Point} p2 - 第二个点.
* @returns {number} 两点之间的距离.
*/
function distance(p1, p2) {
const dx = p2.x - p1.x;
const dy = p2.y - p1.y;
return Math.sqrt(dx ** 2 + dy ** 2);
}
/**
* @type {Point}
*/
const originPoint = { x: 0, y: 0 };
console.log(distance(originPoint, { x: 3, y: 4 }));
在这个例子中：
-
@typedef {object} Point: 定义了一个名为Point的类型，它是一个包含x和y属性的对象，这两个属性都是数字。 -
@param {Point} p1: 指定参数p1的类型为Point。 -
@param {Point} p2: 指定参数p2的类型为Point。 -
@type {Point}: 指定变量originPoint的类型为Point。
生成.d.ts文件:
JSDoc可以生成TypeScript声明文件（.d.ts）。TypeScript编译器（tsc）可以解析JSDoc注释并生成这些文件，这意味着您即使在编写纯JavaScript代码时，也能在IDE中进行类型检查和代码补全。
这是一个基本的tsconfig.json配置：
{
"compilerOptions": {
"target": "es2020",
"module": "commonjs",
"outDir": "./dist",
"declaration": true,
"allowJs": true,
"emitDeclarationOnly": false,
"esModuleInterop": true
},
"include": ["./src/**/*.js"],
"exclude": ["node_modules"]
}
运行npx tsc (或全局安装的tsc) 将在outDir目录下生成.d.ts文件。
总结:
JSDoc结合类型生成提供了一种平衡的方案。您可以获得类型安全和改进的文档，而无需承担完整的TypeScript迁移的成本。对于无法或不需要进行全面TypeScript迁移的项目，这是一种不错的选择，可以逐步引入类型并提升代码质量。 祝您编程愉快！
