在 JSDoc 中，@function 和 @description 是完全不同的两类标签，作用维度截然不同：
✅ 核心区别速览
| 标签 | 类型 | 作用 | 是否必需 | 典型位置 |
|---|---|---|---|---|
@function |
结构标签（声明“这是什么”） | 显式声明标识符为函数，解决解析器识别问题 | ❌ 通常不需要（现代工具可自动识别） | 注释开头，用于非标准函数定义 |
@description |
内容标签（描述“它是什么”） | 提供详细描述文本（多行/含 Markdown） | ❌ 非必需（首段文本自动视为描述） | 描述部分开头，用于结构化长描述 |
🔍 深度解析
1️⃣ @function（或别名 @func）
- 本质：告诉文档解析器 “请将此标识符视为函数”
- 何时需要：
// 情况1：函数表达式（解析器可能无法识别） /** @function */ const util = function() { ... };// 情况2：对象字面量中的方法（需指定名称） const api = {/** @function api.fetchData */fetchData: () => { ... } };// 情况3：命名空间中的函数 /** @namespace utils */ /** @function utils.helper */ utils.helper = () => { ... }; - 何时不需要：
// 标准函数声明 → 解析器自动识别，无需 @function /*** 计算和（首行即描述）* @param {number} a*/ function add(a, b) { ... } // ✅ 完美，无需 @function - 关键点：
- 不提供任何描述内容
- 仅影响解析器如何分类该标识符
- 现代工具（TypeDoc、VS Code）对标准函数声明几乎不需要此标签
2️⃣ @description
- 本质：显式标记描述性文本的开始
- 典型用途：
/*** 简短摘要（自动作为主描述）** @description* 这里是详细说明：* - 支持 **Markdown*** - 可包含多段落* - 适合长文档** @example* add(1, 2) // => 3* @param {number} a*/ function add(a, b) { ... } - 何时需要：
- 描述非常长，需与参数/返回值标签明确分隔
- 需在标签后插入描述（如先写
@deprecated再写描述） - 团队规范要求显式标记描述区块
- 何时不需要：
/*** 计算两数之和（首段自动作为描述）* 支持负数和小数。* @param {number} a*/ function add(a, b) { ... } // ✅ 首段两行均视为描述 - 关键点：
- 不影响标识符类型（函数/类/变量仍由代码结构决定）
- 仅影响生成的文档内容
- 多数场景下可省略（首段文本自动提取为描述）
🌰 对比示例（错误 vs 正确）
❌ 常见误区
/*** @function 计算两数之和 // 错！@function 后不应跟描述文本* @param {number} a*/
function add(a, b) { ... }
→ 工具会将“计算两数之和”解析为函数名（而非描述），导致文档错乱！
✅ 正确写法
// 方案1：最简洁（推荐）
/*** 计算两数之和（首行即描述）* @param {number} a - 被加数* @param {number} b - 加数* @returns {number} 结果*/
function add(a, b) { return a + b; }// 方案2：需长描述时显式用 @description
/*** 计算两数之和* @description* 此函数执行基础加法运算，支持：* - 整数、浮点数* - 负数* - 科学计数法* @param {number} a*/
function add(a, b) { ... }
📊 工具行为对比
| 工具 | @function 作用 |
@description 作用 |
|---|---|---|
| JSDoc (CLI) | 强制将标识符识别为函数 | 将标签后内容作为详细描述 |
| TypeDoc | 通常自动识别，极少需显式声明 | 首段文本自动作为描述，@description 可结构化长文本 |
| VS Code 悬停 | 无直接影响 | 显示首段 + @description 内容 |
| VitePress | 无直接影响 | 渲染为文档主体描述 |
💡 终极建议
| 场景 | 推荐做法 |
|---|---|
| 标准函数声明 | ✅ 直接写描述文本，无需 @function 或 @description |
| 函数表达式/对象方法 | ✅ 仅当工具无法识别时加 @function [name] |
| 描述简短（1-2行） | ✅ 首段写描述，省略 @description |
| 描述很长/含 Markdown | ✅ 用 @description 显式分隔，提升可读性 |
| TypeScript 项目 | ✅ 完全不需要 @function（TS 已明确类型） |
🌟 一句话总结
@function告诉工具 “这是个函数”（解决识别问题）
@description告诉读者 “这个函数是干嘛的”（提供内容）💡 现代项目中：
- 忘掉
@function（除非遇到解析问题）- 慎用
@description（首段文本通常足够）- 专注写好首行描述（最重要！）