文章指出，Svelte框架将类型声明从.ts文件迁移到.js文件的JSDoc注释中，并非反对TypeScript，而是强化了对TypeScript的支持。这一做法澄清了外界误解，表明JSDoc注释与TypeScript类型系统可以协同工作。

标题：JSDoc 就是 TypeScript

2023年5月，Svelte代码库的一个内部重构PR登上Hacker News头条。这个看似具有争议性的PR似乎为TypeScript怀疑论者提供了佐证（当时包括React团队的Dan Abramov等人）。这个主流前端框架标杆公开放弃静态类型检查引发热议，Rich Harris不得不在HN上澄清这"并非对反TypeScript立场的支持"。

Harris解释称，将类型声明从.ts文件迁移到.js文件的JSDoc注释中，恰恰体现了对TypeScript更深入的承诺。这一事件随后引发大量"TypeScript对决JSDoc"的讨论，但本文要强调的是：JSDoc本质上就是TypeScript的另一种形态。

核心论据： 1. 技术同源：TypeScript最初是微软为改善JavaScript开发体验而设计的工具链，其语言服务引擎如今已成为各类编辑器智能提示的基础设施。 2. 底层统一：解析JSDoc注释的正是TypeScript语言服务，因此TypeScript更新日志常包含JSDoc功能改进，且JSDoc项目同样受tsconfig.json配置约束。 3. 实践验证：作者亲测发现： - JSDoc能表达绝大多数TypeScript特性（尽管泛型等语法较冗长） - 代码导航体验更直观（直接跳转实现而非类型声明文件） - 现有TypeScript工具链（如根据后端Schema生成类型）可无缝适配JSDoc

结论：作为TypeScript深度用户，作者强调采用JSDoc并非反对TypeScript，而是通过消除构建步骤获得相同的静态类型分析能力。

注记： 1. Webpack等知名项目也已转向JSDoc方案 2. TypeScript的枚举设计被普遍认为是个历史遗憾 3. TypeScript的许多关键功能说明仅存在于版本更新日志中

以下是评论内容的总结：

支持JSDoc的观点

1. 无构建步骤：JSDoc允许在不增加构建步骤的情况下获得类型检查，适合小型项目或快速开发。

   • "I choose to use it because I didn't want to deal with a build step for a smaller project." (akst)
   • "I’m a fan of anything that allows me to build with javascript that doesn’t require a build step." (prisenco)

2. 开发体验：某些开发者认为JSDoc提供更直接的代码导航体验。

   • "For packages typed with JSDoc, CTRL/CMD clicking on a function will take you to actual code rather than a type declarations file." (crummy)
   • "In WebStorm, jsdoc can be rendered in HTML, which makes the code easier to scan." (efortis)

支持TypeScript的观点

1. 类型表达能力：TypeScript在类型系统的表达能力和完整性上优于JSDoc，尤其是泛型等高级特性。

   • "However, the precision and completeness is not nearly what can be expressed in TypeScript. With generics particularly." (paulddraper)
   • "Today in 2025, TS offers so much more than the (TS)JSDoc implementation. Generics, Enums, Utility types, Type Testing in Vitest, typeguards, plus other stuff." (etoxin)

2. 开发体验：TypeScript提供更好的开发工具支持和更简洁的语法。

   • "The DX with 'real' TypeScript is much, much better than JavaScript with JSDoc, without question." (g947o)
   • "But it’s more annoying than just writing TypeScript. There are ways to express just about everything TypeScript can but they’re all more difficult and convoluted." (afavour)

中立或平衡观点

1. 工具选择取决于场景：根据项目需求和规模选择适合的工具，两者可以结合使用。

   • "Neither is objectively better than the other. Make informed decisions on how you’ll describe your types, and then be consistent and unsurprising." (Waterluvian)
   • "Also, you can use both (if that’s what you prefer)." (Brysonbw)

2. 历史背景：JSDoc和TypeScript的发展背景不同，社区的选择影响了它们的流行度。

   • "The community chose native TS and Google Closure compiler slipped away into the background." (etoxin)
   • "TypeScript won over the alternatives, exactly because it is only a type checker, and not a new language." (pjmlp)

关键争议点

1. 类型导出控制：JSDoc在类型导出控制上存在局限性。

   • "If you define a type in a file with @typedef, it is automatically exported and there is nothing you can do to control that." (llimllib)

2. 生态系统支持：TypeScript在工具链和生态系统支持上更成熟。

   • "npm displays packages with bundled TypeScript declarations." (jcbhmr)
   • "JSDoc-typed node modules require special configuration in consumers to be useful." (jcbhmr)

总结来看，JSDoc和TypeScript各有优劣，选择取决于项目需求、团队偏好和开发场景。TypeScript在类型系统和工具支持上更强大，而JSDoc在无构建步骤和简单项目中有其优势。