为Deno与JSR正确整合JSDoc及类型定义的技术问询

遇到的阻碍 #

• JSDoc类型被忽略：使用JSDoc的@param和@returns标注类型时，deno doc与JSR均不识别，推测二者依赖.d.ts文件获取类型信息。
• .d.ts文件的矛盾问题：
  • deno doc中源码注释与.d.ts注释互斥，需将所有注释迁移至.d.ts，导致源码本身无文档。
  • 编辑器语言服务可识别main.js对应的.d.ts类型，但add.js无法识别；同时deno check对两个文件均报错，例如error: TS7006 [ERROR]: Parameter 'a' implicitly has an 'any' type.（b参数同理）。

核心问题 #

1. 如何让deno check配合@ts-self-types对源码add.js及导入文件main.js生效？
2. 是否无需.d.ts文件，即可让JSDoc类型直接适配deno doc与JSR？

解决方案 #

问题1：让deno check配合@ts-self-types生效 #

1. 为JS文件添加@ts-self-types注释
   在add.js和main.js的文件顶部添加JSDoc注释，指定对应.d.ts文件的路径，示例：

   /** @ts-self-types ./add.d.ts */
   export function add(a, b) {
     return a + b;
   }
   

   路径需与文件实际位置匹配，支持相对或绝对路径。

2. 保证.d.ts类型定义与源码对齐
   .d.ts文件中的函数签名、注释需与源码完全对应，示例add.d.ts：

   /**
    * 两个数字相加
    * @param a 第一个加数
    * @param b 第二个加数
    * @returns 相加结果
    */
   export declare function add(a: number, b: number): number;
   

3. 配置Deno类型检查规则
   在项目根目录的deno.json中添加如下配置，启用TypeScript对JS文件的检查：

   {
     "compilerOptions": {
       "checkJs": true,
       "allowJs": true
     }
   }
   

   完成配置后运行deno check add.js main.js，即可正确识别类型，消除any类型报错。

问题2：无需.d.ts让JSDoc适配deno doc与JSR #

可以直接通过规范的JSDoc实现，无需额外.d.ts文件，步骤如下：

1. 启用Deno的JSDoc类型检查
   在deno.json中开启相关编译选项：

   {
     "compilerOptions": {
       "checkJs": true,
       "allowJs": true,
       "noImplicitAny": true
     }
   }
   

2. 编写规范的JSDoc类型标注
   为函数添加完整的类型信息，遵循TypeScript语法的JSDoc格式，示例：

   /**
    * 两个数字相加
    * @param {number} a 第一个加数
    * @param {number} b 第二个加数
    * @returns {number} 相加结果
    */
   export function add(a, b) {
     return a + b;
   }
   

   注意类型需包裹在大括号内，避免语法错误。

3. 验证deno doc与JSR的兼容性

   • 运行deno doc main.js时，Deno会自动读取JSDoc中的注释与类型，生成符合要求的文档。
   • 发布至JSR时，确保jsr.json配置正确，当前JSR已支持直接解析JS文件中的JSDoc类型；若出现不识别的情况，检查JSDoc是否存在语法错误或遗漏的类型标注。

内容的提问来源于stack exchange，提问作者ZER0