jsdoc 中 @link 和 @see 的区别是什么？

在 JSDoc 中，@link 和 @see 都用于引用其他相关项（如函数、类、外部资源等），但它们的用途、语义和渲染方式有明显区别。以下是详细对比：

---

✅ 1. @see —— “参见”：用于补充参考信息

• 作用：提供额外的参考资料，通常放在文档末尾作为“延伸阅读”。
• 内容：可以是：
  • 其他函数/类的名称（纯文本）
  • URL 链接
  • 任意说明性文字
• 渲染位置：通常在生成的文档中单独列为 “See also” 或 “参考” 区块。
• 不强制解析为链接（除非是有效 URL 或工具支持）。

示例：

/**
 * 计算两个数的和
 * @param {number} a
 * @param {number} b
 * @returns {number}
 * @see {@link subtract} 用于减法
 * @see https://example.com/math-guide
 * @see 还可以参考 multiply 函数
 */
function add(a, b) {
  return a + b;
}

💡 @see 更像是“推荐阅读”，语义较弱，适合放多个参考项。

---

✅ 2. @link —— “内联链接”：用于在描述中创建可点击的超链接

• 作用：在文档正文（如描述、@param、@returns）中内联地引用其他符号或 URL，生成可点击链接。
• 语法：
  • {@link functionName} → 链接到同项目中的函数/类
  • {@link http://example.com} → 链接到外部 URL
  • {@link MyClass#method} → 链接到类的方法
• 必须用花括号包裹：{@link ...}
• 渲染结果：在生成的 HTML 文档中变成 <a> 标签。

示例：

/**
 * 创建一个用户实例。
 * 推荐配合 {@link validateUser} 使用以确保数据合法。
 * 更多信息见 {@link https://api.example.com/users|API 文档}。
 *
 * @param {Object} data - 用户数据
 * @returns {User}
 * @see {@link deleteUser} 删除用户
 */
function createUser(data) {
  // ...
}

💡 @link 是内联的、交互式的，适合在句子中自然引用。

---

🔍 对比总结

特性	@see	@link
用途	补充参考（类似“延伸阅读”）	内联超链接（在描述中直接跳转）
位置	通常独立一行，放在 JSDoc 末尾	嵌入在描述、@param、@returns 等文本中
语法	@see SomeFunction 或 @see http://...	必须写成 {@link SomeFunction}
是否可点击	取决于文档工具（可能只是文本）	总是生成可点击链接（在支持的工具中）
数量	可多个 @see	可多次使用 {@link ...}
语义强度	弱（建议性）	强（直接关联）

---

🛠 工具支持情况

• TypeDoc / VitePress / JSDoc 官方：都支持 @link 内联链接和 @see 参考区块。
• VS Code 智能提示：悬停时，{@link ...} 通常会高亮并可 Ctrl+Click 跳转。
• 最佳实践：
  • 在句子中引用 → 用 {@link fn}
  • 在末尾列相关资源 → 用 @see

---

✅ 推荐用法组合

/**
 * 深度合并两个对象。
 * 注意：此方法不处理循环引用。如需安全合并，请使用 {@link safeDeepMerge}。
 *
 * @param {Object} target - 目标对象
 * @param {Object} source - 源对象
 * @returns {Object} 合并后的对象
 *
 * @see {@link shallowMerge} 浅合并版本
 * @see https://github.com/lodash/lodash/blob/master/merge.md
 */
function deepMerge(target, source) {
  // ...
}

这样既在描述中提供了内联跳转，又在末尾给出了扩展参考，用户体验最佳。