功能說明
一個簡單快速將js、vue等文件中的,多行註釋,提取生成.md文件
使用方法:1、將項目的根目錄下,創建js文件(annotation-export.js),複製粘貼以下文件;2、修改filePath值,修改成要生成文檔的文件地址路徑;3、執行node annotation-export.js,在要生成文檔的文件同級會生成一個.md的文件
- 注:要注意多行註釋的格式,可以根據需要,新增註釋的類型
/* eslint-disable no-unused-vars */
// 文件名爲:annotation-export.js
/**
* 提取頁面多行參數,輸出markdown文件
* 在被提取的文件同目錄生成.md同名文件
* @param {string} [filePath] 被提取的文件路徑
*/
// 多行註釋格式如下
/**
* @method templateFun 方法名稱
* @author webzhang 作者
* @description markdown模板 描述
* @param {array} arr 這個例子數組
* @return {Element}
*/
let filePath = './abb.vue'
let index = filePath.lastIndexOf('.')
let producePath = filePath.slice(0, index) + '.md'
const fs = require('fs')
const path = require('path')
/**
* 檢索字符串中指定的值。返回找到的值,並確定其位置。
* @param {string} reg 正則表達式
* @param {string} str 字符串
*/
function regCommonExec (reg, str) {
let res = reg.exec(str)
reg.lastIndex = 0
return res ? res[1] : ''
}
/**
* 找到一個或多個正則表達式的匹配
* @param {string} reg 正則表達式
* @param {string} str 字符串
*/
function strCommonMatch (reg, str) {
let res = str.match(reg)
return res ? res : []
}
/**
* 解析註釋的每一行
* @param {string} str 字符串
*/
function annotationObj (str) {
// 獲取註釋類型
let annotationReg = /\*\s+\@(.*?)\s/
// 獲取參數類型
let paramTypeReg = /^.+?\{(.+?)\}.*$/
// 獲取參數名稱
let paramNameReg = /^.+?\[(.+?)\].*$/
// 獲取參數文案reg.exec(str)
let paramTextReg = /\s(\w.*)/
return {
category: regCommonExec(annotationReg, str),
name: regCommonExec(paramNameReg, str),
type: regCommonExec(paramTypeReg, str),
text: regCommonExec(paramTextReg, str)
}
}
/**
* @description markdown模板
* @method templateFun
* @author webzhang
* @param {array} arr
* @return {Element} 輸出的數據
*/
function templateFun (arr) {
let paramTable = '| 參數名稱 | 說明 | 參數類型 |\n|: --:|: --:|: --:|\n'
let returnTable = '| 說明 | 輸出類型 |\n|: --:|: --:|: --:|\n'
let defaultObj = {
description: '',
method: '',
author: '',
param: '',
return: ''
}
/**
* @description 註釋每一行對應的模板解析
* @param {object} ele
* @param {string} str
*/
function tempOptionFun (ele, str) {
let tempObj = {
'method': `${ele.text}\n`,
'author': `作者:${ele.text}\n`,
'description': `功能描述:${ele.text}\n`,
'param': `| ${ele.name} | ${ele.text} | ${ele.type} |\n`,
'return': `| 輸出的數據 | ${ele.type} |\n`
}
return tempObj[str]
}
arr.forEach((ele) => {
defaultObj[ele.category] += tempOptionFun(ele, ele.category)
})
return `### ${defaultObj.method}:\n${defaultObj.author}${defaultObj.description}${(defaultObj.param ? paramTable + defaultObj.param : '')}${(defaultObj.return ? returnTable + defaultObj.return : '')}`
}
/**
* 數據處理
* @param {string} str
*/
function processingData (str) {
// 多行註釋的正則
let getAnnReg = /\/\*\*[^.|.]*?\*\//g
// 多行註釋裏的內容
let splitAnnReg = /\*\s@.{1,}/g
// 獲取所有的註釋數據
let annotationArr = strCommonMatch(getAnnReg, str)
let formatArr = []
annotationArr.forEach(element => {
// 獲取參數數據的參數
let paramArr = strCommonMatch(splitAnnReg, element)
let paramObjArr = []
paramArr.forEach(ele => {
paramObjArr.push(annotationObj(ele))
});
// 把參數使用模板進行加工
formatArr.push(templateFun(paramObjArr))
});
return formatArr.join('\n')
}
module.exports = (() => {
/**
* 回寫數據程序
*/
const writeBack = (str) => {
let importString = processingData(str)
const filepath = path.resolve(__dirname, producePath)
fs.writeFile(filepath, importString, 'utf8', () => {
console.log("開始處理數據。。。。")
})
}
let data = fs.readFileSync(filePath);
writeBack(data.toString())
})()