如何在SvelteKit中从JSDoc自动生成文档？

一、基础配置：让TypeScript识别JSDoc类型 #

SvelteKit原生兼容TypeScript，只需在项目根目录的tsconfig.json中调整配置，即可让TS解析JS文件中的JSDoc类型并实现校验：

{
  "compilerOptions": {
    "allowJs": true,          // 允许解析JS文件
    "checkJs": true,          // 开启JS文件的类型检查
    "strict": true,           // 可选，强化类型校验规则
    "moduleResolution": "bundler",
    "target": "ESNext",
    "module": "ESNext"
  },
  "include": ["src/**/*", "svelte.config.js"]
}

配置完成后，VS Code等编辑器会实时提示JSDoc类型错误，实现代码层面的类型安全。

二、Svelte组件中的JSDoc用法 #

1. 组件Props类型定义 #

通过@typedef定义props的结构类型，再用@type标注导出的props变量：

<script>
/**
 * @typedef {Object} UserProps
 * @property {string} name - 用户姓名
 * @property {number} age - 用户年龄
 * @property {boolean} isActive - 用户活跃状态
 */

/** @type {UserProps} */
export let user;
</script>

<div class="user-card">
  <h3>{user.name}</h3>
  <p>年龄：{user.age}</p>
  {#if user.isActive}
    <span class="active-tag">活跃</span>
  {/if}
</div>

这样组件接收props时会自动做类型校验，编辑器也会提供属性补全提示。

2. 工具函数与变量的类型标注 #

组件内导出的工具函数或变量，直接用JSDoc标注参数与返回值类型：

<script>
/**
 * 计算用户出生年份
 * @param {number} currentAge - 用户当前年龄
 * @returns {number} 对应的出生年份
 */
export function calculateBirthYear(currentAge) {
  return new Date().getFullYear() - currentAge;
}
</script>

三、路由与API路由中的JSDoc #

在src/routes下的路由文件中，对请求处理函数进行类型标注：

// src/routes/api/users/+server.js
/**
 * 获取用户列表接口
 * @param {Request} request - 请求对象
 * @returns {Response} 包含用户数组的JSON响应
 */
export async function GET(request) {
  const mockUsers = [
    { name: "张三", age: 28 },
    { name: "李四", age: 32 }
  ];
  return new Response(JSON.stringify(mockUsers), {
    headers: { "Content-Type": "application/json" }
  });
}

四、生成JSDoc文档 #

借助jsdoc工具和svelte-jsdoc插件，可以将Svelte组件、JS文件中的JSDoc注释生成为静态文档：

1. 安装依赖：

npm install jsdoc svelte-jsdoc --save-dev

2. 创建jsdoc.json配置文件：

{
  "plugins": ["svelte-jsdoc"],
  "source": {
    "include": ["src/**/*.svelte", "src/**/*.js"],
    "includePattern": ".+\\.(svelte|js)$"
  },
  "opts": {
    "destination": "./docs",  // 文档输出目录
    "recurse": true
  }
}

3. 在package.json中添加文档生成脚本：

{
  "scripts": {
    "docs": "jsdoc -c jsdoc.json"
  }
}

4. 运行npm run docs，即可在docs目录得到完整的静态文档站点。

五、进阶技巧 #

• 对于SvelteKit内置对象（如$page、$app/stores中的store），可以通过import引用官方TS类型并标注：

/** @type {import('$app/stores').Page} */
$: console.log($page.url.pathname);

• 确保编辑器安装Svelte官方扩展，能更精准地解析组件中的JSDoc注释。

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