JSDoc 讲解

JSDoc 是一种用于为 JavaScript 代码编写注释的工具，类似于 Java 中的 Javadoc。它允许开发者在代码中添加结构化的注释，以便生成文档、提高代码可读性和可维护性。以下是 JSDoc 的一些常用标签及其用途：

1 常用标签

1. @param：描述函数的参数。

   • 格式：@param {类型} 参数名 描述
   • 示例：

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

2. @return：描述函数的返回值。

   • 格式：@return {类型} 描述
   • 示例：

     /**
      * 获取用户的全名。
      * @param {string} firstName 名
      * @param {string} lastName 姓
      * @return {string} 用户的全名
      */
     function getFullName(firstName, lastName) {
         return `${firstName} ${lastName}`;
     }
     

3. @description：提供对函数或方法的详细描述。

   • 示例：

     /**
      * @description 这是一个示例函数，用于演示JSDoc的使用。
      * @param {string} name 用户名
      * @return {string} 问候语
      */
     function greet(name) {
         return `Hello, ${name}!`;
     }
     

4. @example：提供代码示例。

   • 示例：

     /**
      * 计算两个数的乘积。
      * @param {number} a 第一个数
      * @param {number} b 第二个数
      * @return {number} 两数之积
      * @example
      * // 返回 20
      * multiply(4, 5);
      */
     function multiply(a, b) {
         return a * b;
     }
     

5. @see：提供相关链接或参考。

   • 示例：

     /**
      * 计算圆的面积。
      * @param {number} radius 半径
      * @return {number} 圆的面积
      * @see {@link https://en.wikipedia.org/wiki/Area_of_a_circle|圆的面积}
      */
     function getCircleArea(radius) {
         return Math.PI * radius * radius;
     }
     

6. @deprecated：标记已弃用的函数或方法。

   • 示例：

     /**
      * @deprecated 使用新的 `newFunction` 方法代替。
      */
     function oldFunction() {
         // 已弃用的代码
     }