node 基于标准注释的通用文档自动生成器

开发中文档是必不可少的, 但是目前前端可谓是百花齐放, 各种自定义的编译器,后缀名, 导致目前还没有一个很好用的文档生成工具, 可以快速生成整个项目的文档, 随着项目越来越大, 越来越多, 对企业整体的技术管控也带来越来越大的挑战, 如何知道企业内部已经开发了哪些组件, 哪些功能有写好的库可以直接调用, 这些都需要一个文档工具来进行归纳汇总

基于以上问题, 笔者使用node + vue3 + vite 开发了一个文档生成器 特性如下

1. 基于标准注释 /* */ 只需要正常开发中写好注释 文档就已经好了

2. 不限定语言 框架, 只读取文件里的/* /标准注释 不管是vue项目 react项目还是其他的 只要文件里能写 / */ 这种形式的注释

3. 开发模式 实时获取文档数据 打包模式 打包数据随意部署

4. 自定义文件分类, 自定义文件内变量 方法分类

5. 显示文件引用链 可以清晰看到当前文件都引用了其他哪些文件

界面展示如下:

企业微信截图_c004dcf6-819f-495f-9dde-58767ca4e368.png

原理其实很简单, 就是解析 /* */形式的注释 并根据指定的@开头的key值 解析相关数据

目前定义的key值如下:

@doc

此段注释是否要解析成文档

@fileDoc

是否文件描述文档

@type

文档分类 文件描述注释和文件内的注释根据这个字段进行分类

@author

作者 文件作者和文件内部方法 变量等的作者

@name

展示到页面上的名称

@desc

描述

@param

入参

@returns

返回

文件注释如下

/**
 * @doc true
 * @fileDoc true
 * @author xupengfei
 * @name Utils.js
 * @type core
 * @desc global method extend
 */
const fs = require('fs')
const path = require('path')

/**
 * @doc true
 * @name findFile
 * @desc find all file by location dir path
 * @param base location dir path
 * @returns [] all file in location dir path
 */
const findFile = (base) => {
  const files = []
  fs.readdirSync(base).forEach((file) => {
    const curPath = path.join(base, file)
    if (fs.existsSync(curPath)) {
      const stat = fs.lstatSync(curPath)
      if (!stat.isSymbolicLink()) {
        if (stat.isFile()) {
          files.push(curPath)
        } else if (stat.isDirectory()) {
          const sub = findFile(curPath)
          files.push(...sub)
        }
      }
    }
  })
  return files
}

/**
 * @doc true
 * @name uuid
 * @desc make uuid string
 * @param length uuid string length
 * @returns string uuid string
 */
const uuid = (length = 32) => {
  const num = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890'
  let str = ''
  for (let i = 0; i < length; i++) {
    str += num.charAt(Math.floor(Math.random() * num.length))
  }
  return str
}

module.exports = {
  findFile,
  uuid
}

可以看出都是标准注释

安装使用

项目已打成npm包, 可以在任意项目里使用, 或者全局安装也可以

npm install @xpf0000/docs
docs  // 展示此项目的文档
docs src // 展示src目录下的文档
docs src --build outSrc  // 打包src目录下的文档到outSrc

github: https://github.com/xpf0000/docs