前言

JSDocs是各位 大哥们记录代码和编写的代码添加注释的一种方式。此信息显示在工具提示中，使开发人员更容易使用大哥们的代码，不用上来就被说屎山了。

JSDocs 也是一个 API 文档生成器，它扫描文件并根据添加到文件中的 JSDocs 文档生成文档。

您还可以将 JSDocs 转换为 TypeScript，从而更轻松地从 vanilla JavaScript 转换为 TypeScript。

本文简短的指南涵盖了在学习和工作中应用它所需了解的所有内容。

JSDoc 的工作原理：

/**我们可以通过添加带有开始标记和结束标记的块注释来将 JSDocs 添加到函数中**/。这些开始和结束标记之间的任何附加行都包含一个星号*.

注意： 大哥们添加的 JSDoc 必须直接位于您正在记录的代码块之上。

在下面的示例中，我们有一个将两个数字相加并返回结果的函数。此外，我们还添加了一个关于该函数将做什么的简单描述。

/**
 * Adds two values together and returns the result.
 */
function addNumbers(value1, value2) {
  return value1 + value2;
}

大哥们使用该功能时，添加的描述将出现在工具提示中。

上图中：JSDocs 显示在我们的代码完成中。

上图中：JSDocs 显示我们何时添加参数。

我们添加了一个带有描述的 JSDoc。我们现在将看看我们可以包含的不同类型的信息。

参数 ( @param):

JSDocs @param 文档

我们可以使用@param来指示函数的参数并描述它们。

此外，您可以使用花括号指定参数数据类型{}。

/**
 * Adds two numbers together and returns the result.
 * @param {number} value1 The first value
 * @param {number} value2 The second value
 */
function addNumbers(value1, value2) {
  return value1 + value2;
}

上面代码中：JSDocs 使用@param 详细说明参数。

上图中：工具提示中显示的返回信息和数据类型。

返回 ( @returns):

注意： 我们没有指定参数名称，因为返回没有参数名称。

您可以为返回和返回类型添加描述。

/**
 * Adds two numbers together and returns the result.
 * @param {number} value1 - The first value
 * @param {number} value2 - The second value
 * @returns {string} The values that have been added together
 */
function addNumbers(value1, value2) {
  return value1 + value2;
}

上面代码中：JSDocs 使用@returns 详细说明了返回和返回类型

上图中：工具提示中显示的返回信息和数据类型。

使用范例 ( @example):

JSDocs @example 文档

该@example标记可以说是添加到 JSDoc 中最重要的标记。它允许您添加带有语法高亮显示的代码示例，以展示如何使用您编写的代码。

提供代码示例可以让其他开发人员知道如何使用您的代码，从而加快工作流程。

/**
 * Adds two numbers together and returns the result.
 * @param {number} value1 - The first value
 * @param {number} value2 - The second value
 * @returns {string} The values that have been added together
 * @example
 * const a = 10;
 * const b = 20;
 *
 * const result = addNumbers(a, b);
 * console.log(result);
 * // Logs: 30
 */
function addNumbers(value1, value2) {
  return value1 + value2;
}

上面代码中：JSDocs 提供了如何使用自己的代码的示例。

上图中：工具提示中显示了一个代码示例。

弃用代码 ( @deprecated):

JSDocs @deprecated 文档

该@deprecated标记显示该代码已被弃用。弃用的函数将对代码完成中的函数名称产生删除线效果。您可以提供更多信息，例如要使用的替换功能。

/**
 * @deprecated since version 1.0.0
 */
function addNumbers(value1, value2) {
  return value1 + value2;
}

上面代码中：JSDocs deprecated 标记表示代码已弃用。

上图中：工具提示在函数名称上显示了删除线效果，并表示它已被弃用。

自定义类型（@typedef）：

JSDocs @typedef 文档

我们可以使用@typedef标签来记录自定义类型。

在下面的示例中，您将看到我们添加了一个自定义@typedef来记录一个Person对象。添加此 JSDoc 信息使我们能够看到参数上可用的属性，否则这些属性将不会显示。

const person = {
  firstName: 'Michael',
  lastName: 'Scott',
};

/**
 * @typedef {Object} Person
 * @property {string} firstName The person's first name
 * @property {string} lastName The person's last name
 */

/**
 * Greets a person
 * @param {Person} personObject Contains the person's information
 */
function greetPerson(personObject) {
  console.log(`Hello ${personObject.firstName}`);
}

上面代码中：用于为对象创建自定义类型的 JSDocs @typedef 标记。

上图中：来自 @typedef 标记的代码完成和有关对象属性的信息。

React组件：

我们可以使用 JSDocs 来记录我们的组件。

反应组件使用props. 所以我们需要使用@typedef为我们的对象创建一个新的自定义类型props，并将我们的属性添加到这个@typedef自定义类型。

注意： 如果您不使用 TypeScript，您可能想使用better-docs. better-docs将为您节省一些步骤，并使用 PropTypes 生成您的文档。我们不会在本指南中使用 better-docs。

在下面的示例中，我们创建了一个名为的组件Greeting，该组件使用我们传递给该组件的 prop 向用户显示问候消息name。

/**
 * @typedef {Object} Props
 * @property {string} name Name of the user e.g. Lily
 */

/**
 * Displays a greeting to the user.
 * @param {Props} props
 * @example
 * <Greeting name="Lily" />
 * // Displays a greeting message to user called "Lily".
 */
function Greeting({ name }) {
  return <div>Hello {name}!</div>;
}

export default Greeting;

上面代码中：JSDocs @typedef 标签用于记录我们组件的 props。

上图中：我们添加到组件中的 JSDocs。

上图中：显示我们添加的 JSDocs 道具文档的工具提示。

React Hooks：

我们可以记录我们的Hooks，以便其他开发人员可以获得有关我们hooks返回的更多信息。

import { useState } from 'react';

/**
 * @typedef {Object} UseGreetingReturns
 * @property {Function} setNewName Sets a new name
 * @property {Function} getGreeting Returns a greeting message
 */

/**
 * Hook that is used for greeting a user
 * @returns {UseGreetingReturns}
 * @example
 * const {setNewName, getGreeting} = useGreeting()
 *
 * // Set a new name
 * setNewName('John');
 *
 * // Get a new greeting
 * const greeting getGreeting()
 * console.log(greeting);
 * // Logs:
 * // Hello John!
 */
function useGreeting() {
  const [name, setName] = useState('Lily');

  function setNewName(newName) {
    setName(newName);
  }

  function getGreeting() {
    return `Hello ${name}!`;
  }

  return { setNewName, getGreeting };
}

export default useGreeting;

上面代码中：JSDocs @typedef 用于记录我们的钩子的返回值。

上图中：我们为钩子添加的 JSDoc。

上图中：工具提示显示了我们为钩子返回添加的 JSDocs 文档。

生成 JSDocs 文档：

我们可以从添加到代码中的 JSDocs 生成文档。

安装：

我们首先需要在全局或本地安装 JSDocs。

全局安装：

npm install -g jsdoc

本地安装：

npm install — save-dev jsdoc

注意： 如果您在本地安装 JSDocs，则需要从node_modules文件夹运行它：./node_modules/jsdoc/jsdoc.js /src -r. 或者，您可以将它作为脚本添加到您的 package.json 中，例如"jsdocs": "jsdoc /src -r"。

生成文件：

安装 JSDocs 后，您可以运行以下命令为名为 index.js 的文件生成文档。

jsdoc index.js

在单个文件上运行 JSDocs 没有多大用处。以下示例将为src目录中的所有文件递归运行 JSDocs 生成：

jsdoc src -r

查看文档：

默认情况下，文档将输出到名为out.

在此文件夹中，您会找到一个index.html可以使用 Live Server 或类似工具打开的页面。打开后，您将看到我们生成的文档。

总结：

有效使用 JSDocs 可以使大哥们的代码更上一层楼,我希望这篇文章对您有所帮助。

又帮助大哥们学习（摸鱼）了5分钟时间。

生活不易 且行且珍惜 只争朝夕,不负韶华