极客教程在JSDoc中的文档注释
在JSDoc中，我们需要通过代码包含文档注释，JSDoc将生成一个HTML文档网站。让我们看看如何为不同类型的代码创建文档注释。
字符串、数字和数组：
Javascript
/**
* Site Name
* @type {string}
*/
const siteName = "GeeksForGeeks";
/**
* Number
* @type {number}
*/
const number = 1000;
/**
* Array
* @type {Array<number>}
*/
const myArray = [10, 20, 30];
在这里，我们使用简单的JSDoc注释来描述变量及其数据类型，数据类型通过 @type 标签表示。
对象：
Javascript
/**
* Site object
* @type {{id: number, name: string, rank: number|string}}
*/
const site = {
id: 1,
name: "gfg",
rank: 1,
};
在上面的评论中，我们已经指定了对象的所有属性的类型。
功能/方法：
Javascript
/**
* Calculate age
* @param {number} current Current year
* @param {number} yearOfBirth Year of Birth
* @returns {string} your calculated age
*/
const calcAge = (current, yearOfBirth) => {
return `${current - yearOfBirth}`;
};
在这里， @param 标签用于记录函数的不同参数，而 @returns 标签记录函数的返回值
类：
Javascript
/**
* Class to create new owner
*/
class Owner {
/**
* Owner details
* @param {Object} ownerDetail
*/
constructor(ownerDetail) {
/**
* @property {string} name Owner name
*/
this.name = ownerDetail.name;
/**
* @property {number} age Owner's age
*/
this.age = ownerDetail.age;
}
/**
* @property {Function} printOwner Prints Owner's details
* @returns {void}
*/
printOwner() {
console.log(`Owner's name is {this.name}
and his age is{this.age}`);
}
}
说明：
- 在类声明之前，我们有JSDoc注释来描述这个类
- 对于构造函数，使用类似于函数的JSDoc注释
- 在构造函数内部，使用 @property 标签来记录变量
将实例与类联系起来
由于我们创建了一个名为“Owner”的类，因此让我们创建一个该类的实例并使用 @link 标签将其与类关联起来
Javascript
/**
* Link to Owner Class
* See {@link Owner}
*/
const gfg = new Owner({
name: "GeeksForGeeks",
age: 13,
});
最终的 index.js 文件：
Javascript
// @ts-check
/**
* Site Name
* @type {string}
*/
const siteName = "GeeksForGeeks";
/**
* Number
* @type {number}
*/
const number = 1000;
/**
* Array
* @type {Array<number>}
*/
const myArray = [10, 20, 30];
/**
* Site object
* @type {{id: number, name: string, rank: number|string}}
*/
const site = {
id: 1,
name: "gfg",
rank: 1,
};
/**
* Calculate age
* @param {number} current Current year
* @param {number} yearOfBirth Year of Birth
* @returns {string} your calculated age
*/
const calcAge = (current, yearOfBirth) => {
return `{current - yearOfBirth}`;
};
/**
* Class to create new owner
*/
class Owner {
/**
* Owner details
* @param {Object} ownerDetail
*/
constructor(ownerDetail) {
/**
* @property {string} name Owner name
*/
this.name = ownerDetail.name;
/**
* @property {number} age Owner's age
*/
this.age = ownerDetail.age;
}
/**
* @property {Function} printOwner Prints Owner's details
* @returns {void}
*/
printOwner() {
console.log(`Owner's name is{this.name} and his age is ${this.age}`);
}
}
/**
* Link to Owner Class
* See {@link Owner}
*/
const gfg = new Owner({
name: "GeeksForGeeks",
age: 13,
});
输出： 运行以下jsdoc命令：
npm run jsdoc
执行命令后，在jsdoc文件夹中会创建一个index.html页面，在浏览器中打开该页面可以查看由jsdoc生成的文档网站。
文档网站输出：
JSDoc注释中常用的一些标签：
- @author – 用于记录代码的作者。
- @constant – 用于记录常量。
- @default – 允许记录给某个东西的默认值。
- @function – 该标签用于描述函数或方法。
- @global – 文档化全局对象。
- @implements – 用于记录接口的实现。
- @member – 文档化函数的成员。
- @module – 用于文档化JavaScript模块。
- @param – 这个标签用于文档化函数的参数。
- @returns – 用于文档化函数的返回值。
- @type – 用于文档化变量的类型。