jsdoc常见的注释标签

JSDoc 是一种 JavaScript 文档生成工具，它使用特殊的注释格式来注释源代码，然后生成一个 HTML 格式的文档。这些注释遵循一定的格式，以便 JSDoc 工具能够解析并生成相应的文档。以下是一些常见的 JSDoc 注释标签：

1. @param - 描述函数参数。

   /**
    * 这是一个示例函数。
    * @param {string} name - 用户的名字。
    */
   function greet(name) {
     // ...
   }
   

2. @return 或 @returns - 描述函数返回值。

   /**
    * 获取用户的全名。
    * @return {string} 格式化的全名。
    */
   function getFullName() {
     return this.firstName + ' ' + this.lastName;
   }
   

3. @type - 描述变量或函数返回值的类型。

   /**
    * 用户的年龄
    * @type {number}
    */
   let age;
   

4. @throws 或 @exception - 描述函数可能抛出的错误。

   /**
    * 一个可能抛出错误的函数
    * @throws {TypeError} 如果传入的不是字符串。
    */
   function process(input) {
     if (typeof input !== 'string') {
       throw new TypeError('Input must be a string.');
     }
   }
   

5. @this - 描述 this 在函数中的绑定。

   /**
    * 构造函数
    * @this {User}
    */
   function User(name) {
     this.name = name;
   }
   

6. @private - 标记成员为私有。

   /**
    * 私有变量
    * @private
    */
   this._secret = 'secret';
   

7. @public - 标记成员为公开。

   /**
    * 公开变量
    * @public
    */
   this.publicVar = 'public';
   

8. @static - 标记成员为静态。

   /**
    * 静态方法
    * @static
    */
   MyClass.staticMethod = function() {
     // ...
   };
   

9. @name - 指定文档中的名称。

   /**
    * @name MyNamespace.MyClass
    * @class
    */
   var MyClass = function() {
     // ...
   };
   

10. @description 或 @desc - 提供一个简短的描述。

    /**
     * 描述这个函数的作用。
     * @description 这是一个示例函数。
     */
    function myFunction() {
      // ...
    }
    

11. @example - 提供一个代码示例。

    /**
     * 一个示例函数。
     * @example
     * myFunction('hello world');
     */
    function myFunction(arg) {
      // ...
    }
    

12. @version - 指定版本号。

    /**
     * @version 1.0.0
     */
    

13. @see - 引用其他文档。

    /**
     * 这个函数与另一个函数相关。
     * @see OtherFunction
     */
    function myFunction() {
      // ...
    }
    

14. @ignore - 忽略某个成员不被 JSDoc 工具处理。

15. @class - 标记一个类。

    /**
     * 描述这个类。
     * @class
     */
    function MyClass() {
      // ...
    }
    

16. @module - 描述一个模块。

    /**
     * 描述这个模块。
     * @module myModule
     */
    

17. @file 或 @fileoverview - 描述一个文件。