前言
在编程的世界里，我们总希望代码能够自我表达，但现实往往却是“代码千万行，注释没几行”。当你接手一段没有注释的代码时，是不是感觉自己像个占卜师，试图解读前任开发者的心思？别急，今天咱们就来聊聊如何用JSDoc这本“魔法书”来施法，让你的代码变得能说会道！

JSDoc：代码的“翻译官”
JSDoc不仅仅是注释，它是代码的“翻译官”，能让代码的意图跃然纸上。它通过特定的注释格式，为编辑器和IDE提供了丰富的上下文信息，从而实现智能提示、类型检查等功能。接下来，就让我们一起来看看JSDoc的魔力吧！

@param：参数的自我介绍

/**
 * 计算两个数字的和
 * @param {number} a 第一个加数
 * @param {number} b 第二个加数
 * @returns {number} 两数之和
 */
function sum(a, b) {
  return a + b;
}

有了@param，每个参数都仿佛会说话，告诉后来者它们的名字和身份。

@returns：函数的承诺

/**
 * 描述一个数字是否为偶数
 * @param {number} num 要检查的数字
 * @returns {boolean} 如果数字是偶数，返回true，否则返回false
 */
function isEven(num) {
  return num % 2 === 0;
}

@returns是函数的承诺，它告诉你函数会返回什么样的结果。

@typedef：自定义类型的诞生

/**
 * @typedef {Object} Point
 * @property {number} x - 水平坐标
 * @property {number} y - 垂直坐标
 */

/**
 * 计算两点之间的距离
 * @param {Point} point1 第一个点
 * @param {Point} point2 第二个点
 * @returns {number} 两点之间的距离
 */
function calculateDistance(point1, point2) {
  const dx = point1.x - point2.x;
  const dy = point1.y - point2.y;
  return Math.sqrt(dx * dx + dy * dy);
}

通过@typedef，我们可以定义自己的类型，让代码更加清晰和易于管理。

@example：用实例说话

/**
 * 一个简单的加法函数
 * @param {number} a 第一个加数
 * @param {number} b 第二个加数
 * @returns {number} 两数之和
 * @example
 * console.log(add(1, 2)); // 输出：3
 */
function add(a, b) {
  return a + b;
}

@example让函数通过实例来展示它的用法，比长篇大论的说明更加直观。

@deprecated：告别旧时光

/**
 * 一个已经被废弃的方法
 * @deprecated 从版本2.0起，推荐使用`newFunction`替代
 */
function oldFunction() {
  console.warn('这个方法已经被废弃了');
}

@deprecated是向过去告别的标签，它告诉开发者，是时候向前看了。

总结：JSDoc——代码的“语言大师”
通过这篇文章，我们一起学习使用JSDoc来提升代码的表达能力。它不仅提高了代码的可读性和可维护性，还能在不引入TypeScript的情况下，享受到类型标注的便利。

在实际开发中，我的经验是，不要等到代码写完后再去写注释，而是在编写代码的同时，用JSDoc来记录你的思考和决策。这样，无论是现在还是未来，无论是你自己还是其他开发者，都能快速理解代码的意图。记住，代码是给人看的，JSDoc只是一个辅助工具，它不能代替清晰的代码逻辑和良好的编程习惯。