由于 我们使用了ES6高级语法,发现钟爱的 jsduck 不能用了。只能选择 jsdoc。
环境:node14
第1步:运行 npm i jsdoc -g
第2步:
编写配置文件
{"tags": {"allowUnknownTags": true},"source": {"include": ["./src/canvas/"],"includePattern": ".+\\.js(doc|x)?$","excludePattern": "(^|\\/|\\\\)_","exclude": ["./src/main.js"]},"plugins": [],"opts": {"encoding": "utf8","destination": "./doc/doc-page/","recurse": true},"templates": {"cleverLinks": false,"monospaceLinks": false,"default": {"outputSourceFiles": true}}
}
其中 比较重要的提一下,source->include 里面的地址是你要处理的源文件js目录。opts->destination 代表 你要输出的地址目录。
第3步:
由于我将jsdoc安装在了全局,所以直接运行 :
jsdoc -c jsconfig.json
到这里基本就结束了。理想情况,会在 ./doc/doc-page/ 里生成文档。
运行上面的命令可能会出现下面的类似错误,尤其是 win10环境(我就遇到了)
AuthorizationManager check failed.
At line:1 char:1
+ C:\scriptpath\scriptname.ps1
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+ CategoryInfo : SecurityError: (:) [], PSSecurityException+ FullyQualifiedErrorId : UnauthorizedAccess
解决办法:
https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.security/set-executionpolicy?view=powershell-7.1
具体就是 管理员 cmd 进入命令行,输入 Set-ExecutionPolicy ,然后 输入 A (代表全部的意思),即可。再次运行就好了。
Set-ExecutionPolicy[-ExecutionPolicy] <ExecutionPolicy>[[-Scope] <ExecutionPolicyScope>][-Force][-WhatIf][-Confirm][<CommonParameters>]
这里贴出一个常用的批处理的jsdoc 命令:
"D:\a\node_modules\.bin\jsdoc" "D:\a\src\main\webapp\WEB-INF\src\canvas" -r -d "D:\a\src\main\webapp\WEB-INF\doc"
-r 是递归源文件的子目录
中间的目录是源文件;最后的目录是doc生成目录
第1个目录是jsdoc 插件命令,信息的你会发现。我是执行了 npm i jsdoc --save-dev 或 npm i jsdoc --save .并没有安装到全局。
所以,这里必须使用具体jsdoc命令(即jsdoc.cmd)的详细地址(注意不是 jsdoc的所在 node_modules的jsdoc目录),而是./bin/jsdoc.cmd