前端-jsdoc-快速搭建

不念不忘少年蓝@ 2022-11-15 11:55 137阅读 0赞

由于 我们使用了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][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

[https_docs.microsoft.com_en-us_powershell_module_microsoft.powershell.security_set-executionpolicy_view_powershell-7.1]: https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.security/set-executionpolicy?view=powershell-7.1