详解VSCode中使用JSDoc注释注释JavaScript代码|极客教程

详解VSCode中使用JSDoc注释注释JavaScript代码

简介

在编写JavaScript代码时，我们经常需要添加注释来标记代码的功能、参数、返回值等信息，这对于代码的维护和阅读非常有帮助。而JSDoc（JavaScript Documentation）是一种可以实现JavaScript代码注释的规范和工具。在VSCode中，我们可以利用JSDoc规范为我们的JavaScript代码添加详细注释，提高代码的可读性和可维护性。

本文将详细介绍如何在VSCode中使用JSDoc注释注释JavaScript代码，包括JSDoc的基本语法和常用标记、如何为函数、变量、类等添加JSDoc注释以及如何优化VSCode的JSDoc插件等。

JSDoc的基本语法和常用标记

JSDoc的格式

JSDoc注释以/**开始，在每行注释前以*标记，最后以*/结束。在JSDoc注释中，可以使用特定的标记标识不同的信息，比如函数的参数、返回值、可抛出的异常等。

/**
 * 这是一个简单的JSDoc注释示例
 */

JSDoc标记

@param {type} paramName - 参数描述：用于描述函数的参数，{type}表示参数的类型，paramName表示参数的名称，参数描述为对参数的描述。
@return {type} - 返回值描述：用于描述函数的返回值，{type}表示返回值的类型，返回值描述为对返回值的描述。
@throws {type} - 异常描述：用于描述函数可能抛出的异常，{type}表示异常的类型，异常描述为对异常的描述。

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

为函数、变量、类添加JSDoc注释

为函数添加JSDoc注释

在定义函数时，可以使用JSDoc注释为函数添加详细注释，包括函数的功能、参数、返回值等信息。

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

为变量添加JSDoc注释

对于变量，可以使用JSDoc注释说明变量的意义和类型。

/**
 * @type {number}
 */
let num = 10;

为类添加JSDoc注释

对于类，可以使用JSDoc注释说明类的功能、属性、方法等信息。

/**
 * 表示一个人的类
 */
class Person {
    /**
     * 创建一个人的实例
     * @param {string} name - 人的姓名
     */
    constructor(name) {
        this.name = name;
    }

    /**
     * 打招呼
     */
    sayHello() {
        console.log(`Hello, my name is ${this.name}.`);
    }
}