JSDoc 综合指南

JavaScript 是一种动态类型语言，不提供内置类型检查或文档执行。这可能会导致较大的代码库出现混乱，尤其是在团队合作时。

输入 JSDoc — 一个强大的工具，用于记录您的代码、提供类型安全性并改善协作。

本指南将深入探讨 JSDoc、它的优点以及如何在 JavaScript 和 TypeScript 项目中有效地使用它。

什么是 JSDoc？🤔

JSDoc 是一种文档标准，允许开发人员向其 JavaScript 代码添加结构化注释。这些注释用于描述代码功能、定义预期参数类型、返回值等。

VS Code 和许多 IDE 等工具使用这些注释来提供内联文档和类型提示。

设置 JSDoc ⚓

要开始使用 JSDoc，如果您只是使用它来获取文档和输入提示，则不需要进行任何特殊安装。

但是，如果您想生成 HTML 文档，则需要 JSDoc CLI。

**1- 安装 JSDoc：**

npm install -g jsdoc

**2- 生成文档：**

jsdoc yourFile.js -d docs

此命令在名为“docs”的文件夹中生成文档。

编写 JSDoc 注释

JSDoc 注释以 /** 开头，位于要记录的代码元素上方。以下是示例：

/**
 * Adds two numbers together.
 * @param {number} a - The first number.
 * @param {number} b - The second number.
 * @returns {number} The sum of the two numbers.
 */
function add(a, b) {
    return a + b;
}

常用的 JSDoc 标签💯

**1-@param：描述一个函数参数。**

/**
 * @param {string} name - The name of the user.
 */
function greet(name) {
    console.log(`Hello, ${name}!`);
}

**2-@returns：指定函数的返回类型。**

/**
 * @returns {boolean} Whether the operation was successful.
 */
function isOperationSuccessful() {
    return true;
}

**3- @type：用于变量类型注释。**

/** @type {string} */
let username = "JohnDoe";

**4- @typedef 和 @property：定义自定义类型。**

/**
 * @typedef {Object} User
 * @property {string} name - The name of the user.
 * @property {number} age - The age of the user.
 */

/** @type {User} */
const user = { name: "Alice", age: 25 };

**5-@example：提供使用示例。**

/**
 * Calculates the area of a rectangle.
 * @param {number} width - The width of the rectangle.
 * @param {number} height - The height of the rectangle.
 * @returns {number} The area of the rectangle.
 * @example
 * const area = calculateArea(5, 10);
 * console.log(area); // 50
 */
function calculateArea(width, height) {
    return width * height;
}

TypeScript 中的 JSDoc

虽然 TypeScript 已经提供了静态类型检查，但您仍然可以使用 JSDoc 来生成文档。

TypeScript 原生支持 JSDoc，你甚至可以在 `.js` 文件中使用 JSDoc 来利用 TypeScript 的类型检查，而无需迁移到 `.ts`。

/**
 * Divides two numbers.
 * @param {number} numerator - The numerator.
 * @param {number} denominator - The denominator.
 * @returns {number} The result of the division.
 */
function divide(numerator, denominator) {
    if (denominator === 0) {
        throw new Error("Cannot divide by zero.");
    }
    return numerator / denominator;
}

在 TypeScript 文件中，JSDoc 注释可以增强您的 IDE 体验并提供更好的协作。

使用 JSDoc 的好处

提高可读性：结构化的注释使您的代码不言自明。

类型安全：VS Code 等工具利用 JSDoc 在 JavaScript 文件中提供类型提示。

无缝入职：新团队成员可以快速了解功能和对象的目的和用途。

文档生成：轻松为您的代码库生成 HTML 文档。

与 JSDoc 配合使用的工具

VS Code：提供内联类型提示和参数建议。

TypeScript 编译器：为带有 JSDoc 注释的 .js 文件提供类型检查。

JSDoc CLI：生成静态文档。

结论

对于任何希望提高代码质量、可维护性和协作的 JavaScript 开发人员来说，JSDoc 都是不可或缺的工具。

无论您是在单独开展项目还是与团队合作，将 JSDoc 集成到您的工作流程中都可以确保您的代码不仅具有功能性，而且易于理解和访问。

**🌐 与我联系：**

📍 LinkedIn

📍X（推特）

📍 电报

📍 Instagram

CLIS.CC