jsdoc-to-markdown实现js文件的文档生成
导读
这个需求有点怪,之前基本都是后台生成文档,前端对接就行了。
不过当团队大了,或者异地办公等原因,导致前端也需要进行对接,因此有了这篇文章。
开发环境
版本号 | 描述 | |
---|---|---|
文章日期 | 2022-10-27 | |
操作系统 | Win10-1607 | |
nvm version | 1.1.9 | |
node -v | v12.22.12 | npm -v (6.14.16) |
IDEA | 2021.3 | |
安装Vs code插件:Doxygen Documentation Generator
插件安装后,直接输入
/**
,会自动弹出注释的选项,我们选择Document This
的选项。如下图:
效果
/**
* 功能设置:
*
* @example
* await setValue('mega_money', true);
* @param {*} target
* @param {*} arg
* @param {string} [source='']
* @param {number} [cheatId=0]
* @returns undefined
* @memberof Trainer
*/
async setValue(target, arg, source='', cheatId=0) {
优势
- 支持多种语言
- 自动识别参数及类型
jsdoc-to-markdown的使用
了解 jsdoc
jsdoc-to-markdown
基于jsdoc
实现的,可以参考文章《jsdoc接口文档生成器》https://blog.csdn.net/youlinhuanyan/article/details/105667770
jsdoc-to-markdown安装
全局安装:npm install -g jsdoc-to-markdown
创建测试文件example.js
/**
* A quite wonderful function.
* @param {object} - Privacy gown
* @param {object} - Security
* @returns {survival}
*/
function protection (cloak, dagger) {}
jsdoc-to-markdown使用
单文件:
jsdoc2md example.js
多文件:jsdoc2md -f example.js example2.js > all.md
编程方式实现
https://github.com/jsdoc2md/jsdoc-to-markdown/wiki/How-to-create-one-output-file-per-class
'use strict'
const jsdoc2md = require('jsdoc-to-markdown')
const fs = require('fs')
const path = require('path')
/* input and output paths */
const inputFile = 'example.js'
const outputDir = __dirname
/* get template data */
const templateData = jsdoc2md.getTemplateDataSync({ files: inputFile })
/* reduce templateData to an array of class names */
const classNames = templateData.reduce((classNames, identifier) => {
if (identifier.kind === 'class') classNames.push(identifier.name)
return classNames
}, [])
/* create a documentation file for each class */
for (const className of classNames) {
const template = `{{#class name="${className}"}}{{>docs}}{{/class}}`
console.log(`rendering ${className}, template: ${template}`)
const output = jsdoc2md.renderSync({ data: templateData, template: template })
fs.writeFileSync(path.resolve(outputDir, `${className}.md`), output)
}
jsdoc-to-markdown踩坑!!!
上面说的是官网教程,不过执行完后,小编的电脑会报下面的错误:
JSDOC_ERROR: There are no input files to process.
众里寻他千百度,终于在stackoverflow上找到了答案:
我的jsdoc是全局安装的,配置文件所在目录为
J:\Users\Administrator\AppData\Roaming\nvm\v12.22.12\node_modules\jsdoc-to-markdown\node_modules\jsdoc
。
|
everything全局搜索文件jsdoc\conf.json.EXAMPLE
所在目录就是了,创建个文件名为conf.json
的配置,填入下面配置:
{
"tags": {
"allowUnknownTags": true
},
"source": {
"include": ["."]
},
"plugins": [],
"templates": {
"cleverLinks": false,
"monospaceLinks": false,
"default": {
"outputSourceFiles": true
}
}
}
参考资料
- Vs code自动生成Doxygen格式注释 https://www.cnblogs.com/silencehuan/p/11875958.html
- jsdoc-to-markdown官网 https://github.com/jsdoc2md/jsdoc-to-markdown
- 踩坑原文 https://stackoverflow.com/questions/64978721/js-includepattern-not-working-there-are-no-input-files-to-process
这篇好文章是转载于:学新通技术网
- 版权申明: 本站部分内容来自互联网,仅供学习及演示用,请勿用于商业和其他非法用途。如果侵犯了您的权益请与我们联系,请提供相关证据及您的身份证明,我们将在收到邮件后48小时内删除。
- 本站站名: 学新通技术网
- 本文地址: /boutique/detail/tanhficbic
-
photoshop保存的图片太大微信发不了怎么办
PHP中文网 06-15 -
《学习通》视频自动暂停处理方法
HelloWorld317 07-05 -
word里面弄一个表格后上面的标题会跑到下面怎么办
PHP中文网 06-20 -
Android 11 保存文件到外部存储,并分享文件
Luke 10-12 -
photoshop扩展功能面板显示灰色怎么办
PHP中文网 06-14 -
微信公众号没有声音提示怎么办
PHP中文网 03-31 -
excel下划线不显示怎么办
PHP中文网 06-23 -
excel打印预览压线压字怎么办
PHP中文网 06-22 -
TikTok加速器哪个好免费的TK加速器推荐
TK小达人 10-01 -
怎样阻止微信小程序自动打开
PHP中文网 06-13