只需一行代码即可在 Node.js 中生成仿 jsDoc 的文档！

2023-12-15 03:28:46

近年来，jsDoc 一直是 JavaScript 开发人员文档化其代码的首选工具。它可以通过提取注释中的信息来生成丰富的文档。但是，为每个函数和类编写详细的注释可能是一项繁琐且耗时的任务。

借助 Node.js 文件模块的强大功能，我们可以创建工具来简化 jsDoc 文档的生成过程。本指南将向您展示如何使用不到 50 行代码编写一个命令行实用程序，只需一行命令即可生成仿 jsDoc 的文档。

前提条件

在继续之前，请确保您已安装 Node.js 和 npm。

步骤 1：创建一个新项目

创建一个新的 Node.js 项目并安装必要的依赖项：

mkdir jsdoc-generator
cd jsdoc-generator
npm init -y
npm install jsdoc@^4.0.0

步骤 2：创建实用程序脚本

在 jsdoc-generator 目录中创建一个名为 index.js 的新文件，并添加以下代码：

const jsdoc = require('jsdoc');
const fs = require('fs');

const generateDocs = (input, output) => {
  const parserOptions = {
    pedantic: true,
    recurse: true,
  };

  jsdoc.process({
    files: input.split(','),
    destination: output,
    parser: parserOptions,
    configure: 'jsdoc.json',
  });
};

const args = process.argv.slice(2);
if (args.length !== 2) {
  console.error('Usage: node index.js <input files> <output directory>');
  process.exit(1);
}

const inputFiles = args[0];
const outputDir = args[1];

generateDocs(inputFiles, outputDir);

步骤 3：编写 jsdoc 配置文件

在项目根目录中创建名为 jsdoc.json 的文件，并添加以下配置：

{
  "source": {
    "excludePattern": "(node_modules/|\\.test\\.js$)"
  },
  "plugins": [
    "plugins/markdown"
  ],
  "templates": {
    "default": {
      "layoutFile": "node_modules/jsdoc/templates/default/layout.tmpl",
      "staticFiles": {
        "stylesheets": [
          "css/style.css"
        ]
      }
    }
  },
  "destination": "./docs"
}