JSDoc 介绍使用规范JsDoc的使用介绍

下面是关于JSDoc的完整攻略。

JSDoc 介绍

JSDoc是一个用于生成JavaScript代码文档的工具，它基于JavaScript的文档注释来生成文档。JSDoc支持多种标记，并且可以生成HTML、Markdown等多种格式的文档，因此广泛应用于JavaScript项目的文档生成中。

使用规范

以下是一些JSDoc的使用规范：

常见标记

• @param {type} name description：用于声明函数的参数类型和名称以及参数描述。
• @returns {type} description：用于声明函数的返回值类型和返回值描述。
• @type {type} description：用于声明变量的类型和变量描述。

代码示例

以下是一个使用JSDoc的示例：

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

在这个例子中，我们使用了@param标记来声明num1和num2的类型和名称，并使用了@returns标记来声明函数的返回值类型和描述。

以下是另一个例子，演示了如何使用@type标记声明变量类型：

/**
 * 描述一个人的信息
 * @typedef {Object} Person
 * @property {string} name - 姓名
 * @property {number} age - 年龄
 * @property {string} gender - 性别
 */

/**
 * 创建一个新的人
 * @param {string} name 姓名
 * @param {number} age 年龄
 * @param {string} gender 性别
 * @returns {Person} 新的人对象
 */
function createPerson(name, age, gender) {
    return {
        name: name,
        age: age,
        gender: gender
    };
}

在这个例子中，我们使用了@typedef标记来声明一个名为Person的类型，它可以理解为是一个包含name、age、gender属性的对象，而createPerson函数返回一个Person对象。

以上是JSDoc的使用规范和示例，如有疑问，欢迎提出。