@function 和 @description 的区别是什么

在 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（首段文本通常足够）
• 专注写好首行描述（最重要！）