用JSDocs记录JavaScript代码

假设你今天为一个软件写了一个代码块，或者写了几个函数来实现一个特定的功能。在写代码的那一刻，你的脑海中一切都很清晰，你可以理解代码中的每一块、每一行都在做什么。然而，几个月后，你可能会看着自己的代码，怀疑自己是否就是那个写代码的人，特别是在代码没有被记录的情况下。

代码文档解决了忘记代码是什么的问题，并使其他开发者容易理解如何使用和维护你写的软件。

为什么你需要JSDocs

我们都知道，编写代码文档是非常乏味的。因此，我们需要一些东西来削减时间。JSDocs的主要思想是为函数、类和方法生成文档。

为你的代码使用JSDocs的好处是，它很容易导出到HTML。此外，它与IDE和代码编辑器整合得很好，如VS Code，它有一个扩展。

目标

在本教程结束时，读者应该已经学会了如何在JavaScript程序中初始化JSDocs，并在现实生活的编程场景中使用它。我们将编写使用JSDocs记录的代码片断来演示这一概念。

洞察力

如果你看一下下面的函数，很容易就能知道这个函数是做什么的，因为它自己会说话。

从函数名到它的参数，我们可以知道这个函数通过把长度和宽度作为参数来计算矩形的面积。

function calculateArea(length, width, area) {
	area = length * width;
	return area;
}

如果我们改变函数和参数的名称，这个函数可能意味着别的东西。我们可以使用JSDocs文档API来帮助我们更好地描述这个函数，而不是让它自己说话。

你在函数名称前添加一行以星号开始的注释* ，来记录它。

/**
* function to  calculate the area of a rectangle
*/
function calculateArea(length, width, area){
    area = length * width;
    return area;
}}

JSDocs注释

仅仅写下函数名是不够的。通过JSDocs注释，我们还可以通过记录参数来使事情变得更加有趣。

对于每个参数，我们注意它的类型和它在代码中的作用描述。一个函数参数的语法如下所示。

/**
 *
 * @param {parameter type} parameter name - parameter description
 *
 */

类型：参数类型可以是string,integer,array,floating-point ，等等。
名称：每个参数都必须有一个名称，以便在代码中和函数被调用时进行引用。
描述：对参数的解释。

项目设置

我们已经对如何使用JSDocs文档API有了初步了解。为了了解更多，请创建一个文件夹并将其命名为project 。

前往你的终端，运行以下命令。

npm init -y
npm i- dev jsdocs

我们需要一个配置文件来使用JSDocs。在应用程序的根文件夹中，创建一个名为jsodc.json 的文件，并粘贴以下片段。

{
	"source": {
		"include": ["source"],
		"includePattern": ".js$",
		"excludePattern": "(node_modules/|docs)"
	},
	"plugins": ["plugins/markdown"],
	"templates": {
		"cleverLinks": true,
		"monospaceLinks": true
	},
	"opts": {
		"recurse": true,
		"destination": "./documentation/"
	}
}

在根文件夹中，创建一个名为source 的新文件夹，并在其中添加一个名为index.js 的新文件。这里是我们要写代码的地方，这些代码将被生成文档。

创建启动脚本

在package.json 文件的脚本对象中添加以下片段。

"doc": "jsdoc -c jsdoc.json"

现在运行命令npm run doc ，之后你会在你的根文件夹中看到一个名为documentation 的文件夹。

这时，你的文件夹结构应该如下图所示。

|-- jsdocs.json
|-- package-lock.json
|-- package.json
|-- documentation
|   |-- index.html
|   |-- fonts
|   |-- scripts
|   |-- style
|-- source
    |-- index.js

如果你在documentation 文件夹中打开你的index.html 文件，你应该看到自动生成的页面，你的文档将在这里。

documentation page

记录数据类型

JavaScript有各种数据类型，如字符串、数字、数组和对象。下面的片段展示了如何使用JSDocs来记录它们。

字符串

/**
 * Documentaion for a string
 * Article Name
 * @type {string}
 */

const articleName = "Javascript Documentation";

数字

/**
 * Documentaion for a Number
 * Article Number
 * @type {number}
 */

const articleNumber = 24;

数组

/**
 * Documentaion for an array
 * Array
 * @type {Array<number>}
 */

const stars = [1, 2, 3, 4, 5];

对象

/**
 * Documentaion for an Object
 * Object
 * @type {{id: number, name: string, class: string}}
 */

var student = {
	id: 23,
	name: "Jane Doe",
	class: "Beginner",
};

文档化函数

现在我们知道了如何为类型创建JSDocs注释，我们可以借用同样的知识来记录函数。

我们描述一个函数是做什么的，它所接受的参数，以及它返回的内容。

/**
 * function to  calculate the area of a rectangle
 * @param {number} length - The length of the rectangle
 * @param {number} width - The width of the rectangle
 * @returns {number} - The area of the rectangle
 */
function calculateArea(length, width, area) {
	area = length * width;
	return area;
}

创建自定义类型

假设我们想创建一个名为programming language 的自定义数据类型。我们将使用typedef 关键字来定义自定义类型，指定语言对象和对象名称。

/**
 * Custom data type defining a programming language
 * @typedef {Object} ProgrammingLanguage
 * @property {number} id - Language id
 * @property {string} name - Language name
 * @property {string} software - Projects it can build
 * @property {number} year - the year it came to life
 */

/**
 * @type {ProgrammingLanguage}
 */

const programmingLanguage = {
	id: 100,
	name: "Javascript",
	software: "Websites",
	year: 1999,
};

使用类的工作

现在我们来看看如何使用JSDocs来记录JavaScript类。

一个JavaScript类通常有一个类名、数据成员和可以对其执行的方法。下面的片段解释了如何在JSDocs中处理类的问题。

/**
 * Class to create a user object
 */
class User {
	/**
	 * @param {Object} userInfo  Information about a user
	 */
	constructor(userInfo) {
		/**
		 * @property {string} name - User name
		 */
		this.name = userInfo.name;

		/**
		 * @property {string} password - User's password
		 */
		this.password = userInfo.password;

		/**
		 * @property {string} email - User's email address
		 */
		this.email = userInfo.email;

		/**
		 * @property {number} age - User's age
		 */
		this.age = userInfo.age;
	}

	/**
	 * @property {Function} sayHello - Greet the group stating user's name
	 * @returns void
	 */
	sayHello() {
		console.log(`Hello section my name is ${this.name}`);
	}
}

Classes

探究模块

也许你想知道如何在同一个项目中使用不同的文档和文件。那么，这里我们就来解决这个问题。

你可以通过将模块导入到source 文件夹中的主文件index.js ，将模块引入到你的文档中。例如，我们可以创建一个叫functions 的模块，在其中写上我们的函数，并把它记录下来。

在source 文件夹中创建一个名为functions.js 的文件，并添加下面的片段。

/**
 * functions module
 * @module functions
 */

/**
 * function to  calculate the area of a rectangle
 * @param {number} length - The length of the rectangle
 * @param {number} width - The width of the rectangle
 * @returns {number} - The area of the rectangle
 */
exports.area = (length, width) => length * width;

/**
 * Add two numbers
 * @param {number} number1 - First number
 * @param {number} number2 - Second number
 * @returns {number} - Sum of number1 and number2
 */
exports.add = (number1, number2) => number1 + number2;

通过在文件顶部添加以下一行，将functions 模块带入index.js 。

const { add, area } = require("./functions");

如果你运行npm run doc 命令，你会看到模块functions 的记录，如下所示。

modules

结论

在本教程中，我们已经学会了如何使用JSDocs来记录JavaScript代码。我们对基本数据类型、数组、对象、函数参数和类的文档化进行了考察。

本教程通过简单易懂的片段给这个主题提供了一个适合初学者的方法，使你能够最大限度地了解这个概念。

如何用JSDocs记录JavaScript代码