『自研』babel插件：通过注释自动生成 js 方法说明文档

简介

这是一款可通过注释块自动输出 js 方法说明文档的babel插件。

功能

基于babel-AST，通过AST树遍历注释块，并将注释块转为说明文档内容输出md文件。

使用

获取代码

先将代码 clone 到本地（由于未发布该插件，所以直接把代码放到本地使用）

git clone git@github.com:DemoJj/outDocs.git

安装相关依赖

npm install 
// 或 cnpm i

配置.babelrc文件

属性	介绍
outDirName	输出所放文件夹的名称
gather	集合所有文档，集合后输出文件的名称

// .babelrc
{
    "plugins": [["./plugins.js", {
      "outDirName": "demoRme",
      "gather": "common" // 集合所有文档，并设定common为文件名
    }] ]
    // "plugins": ["./plugins.js"]
  }

注释块介绍

属性	介绍	备注
@out	含有则输出该函数文档，否则不输出
@description	函数描述
@param	函数参数	{ ‘string’: ‘字符串’,‘number’: ‘数值’,‘array’: ‘数组’,‘object’: ‘对象’}
@returns	函数返回内容

/** @out
 * @description 测试方法
 * @param {string} a 参数一
 * @param {number} b
 * @returns {void}
 */
function square(n) {
    return n * n;
}

使用方案

• 方案1（babel）

在命令行中执行以下命令：

npx babel test/test.js

• 方案2（rollup）(可深度输出)

a. 在根目录下新建 rollup.config.js 文件：

// rollup.config.js
import babel from 'rollup-plugin-babel';
import clear from 'rollup-plugin-clear';
export default {
   input: './test/test.js',
   plugins:[
       clear({
           targets: ['./demoRme']
       }),
       babel()
   ]
}

b.在命令行中执行以下命令：

rollup -c

效果

a. 方案1(babel)默认生成目录：

b. 方案2(rollup)默认生成目录：

c.配置生成目录：

d.输出文档显示内容

源码：
【点此进入】