JSDoc语法规范
JSDoc 是 JavaScript 中用于添加文档注释的一种常见方式。它是一种在注释中使用特定标记和语法来描述代码功能和用法的标准化方式。以下是 JSDoc 的主要语法规范和常见标记：
- 基本注释语法：
/**
* 这里是注释的内容。
*/
- 描述块：描述块通常位于函数、方法、类等代码块之前，用于描述它们的功能和用法。
/**
* 函数用于加法操作。
* @param {number} a - 第一个数字。
* @param {number} b - 第二个数字。
* @returns {number} - 返回两个数字的和。
*/
function add(a, b) {
return a + b;
}
- 标记：JSDoc 使用标记来描述不同的元素和信息。以下是一些常见的标记：
- @param：描述函数参数的类型和用途。
- @returns：描述函数返回值的类型和含义。
- @type：描述变量、对象属性或函数返回值的类型。
- @description：提供关于注释块的更详细描述。
- @example：提供示例代码。
- @see：提供参考链接。
- 类型注释：用于指定变量、参数和返回值的数据类型。
/**
* @param {string} name - 用户名。
* @param {number} age - 年龄。
* @returns {object} - 包含用户信息的对象。
*/
function createUser(name, age) {
// ...
}
- 可选参数和默认值：可以使用方括号表示可选参数，并使用
=指定默认值。
/**
* 将两个数字相加。
* @param {number} a - 第一个数字。
* @param {number} [b=0] - 第二个数字，默认为 0。
* @returns {number} - 返回两个数字的和。
*/
function add(a, b = 0) {
return a + b;
}
- 描述对象属性：用于描述对象属性的类型和用途。
/**
* @typedef {object} User
* @property {string} name - 用户名。
* @property {number} age - 年龄。
*/
7. 类和构造函数：可以使用 @class 标记和 @constructor 标记来描述类和构造函数。
```javascript
/**
* 表示一个人员。
* @class
* @classdesc 这个类用于表示人员信息。
* @param {string} name - 姓名。
* @param {number} age - 年龄。
*/
class Person {
constructor(name, age) {
this.name = name;
this.age = age;
}
}
- 命名空间：可以使用 @namespace 标记来描述命名空间。
/**
* @namespace
* @description 这是一个示例命名空间。
*/
const myNamespace = {
// ...
};
- 其他标记：JSDoc 还支持其他标记，如 @private、@public、@protected 等，用于指定成员的访问权限。
/**
* @private
* @type {number}
*/
const secretNumber = 42;
这只是 JSDoc 的一些基本语法规范和常见标记。你可以根据需要使用更多的标记来描述不同的代码元素，以生成更详细的文档和代码提示。 JSDoc 非常有用，因为它可以帮助团队更好地理解和使用代码，同时也可以自动生成文档，提高代码的可维护性。
