JSDoc使用方法

最新推荐文章于 2024-04-25 12:40:25 发布

weixin_34128839

最新推荐文章于 2024-04-25 12:40:25 发布

阅读量1.2k

点赞数

文章标签： json 前端 python ViewUI

原文链接：https://my.oschina.net/alioveyu/blog/1575879

版权

2019独角兽企业重金招聘Python工程师标准>>>

在软件开发过程中，虽说你的代码可读性很强，但是如果想要让一个新的团队成员快速了解软件的相关结构，一份技术文档是我们最佳的选择。下面就来介绍一下在js中使用jsdoc来快速生成我们所需要的技术文档

安装

全局安装

npm i -g jsodc

本地安装

npm i jsodc

使用示例

jsdoc file_name # file_name可以使用正则匹配

接下来可以看到项目文件夹下多出了一个out文件夹，这就是jsdoc为我们生成的文档了，可能你并不想把jsdoc生成的文档提交到代码库中，那么就需要在代码.gitignore文件中把jsdoc文件夹下的内容全部忽略掉

基本语法

模块

语法

/**
 * @module myModule
 */

如上面这样，一般在文件顶部声明本文件所属的模块，使用@module来声明模块名称。

如果一个模块属于另一个模块，我们可以这样写：

/**
 * @module parentModule/myModule
 */

描述

语法

/**
 * @description my description
 */

描述的关键字是@description，后面就直接跟我们需要对类、函数、属性等的描述内容就可以了。还有一点就是当我们的描述在注释中的第一句的时候，可以省略@description关键字，直接写我们的描述，像下面这样：

/**
 * my description it no @description keyword
 */

参数

语法

/**
 * @param {Object} param1 param1 description
 * @param {String} param2 param2 description
 * @param {Number} param3
 * @param {Array} param4
 * @param {Function} param5
 */

参数用@param关键字来声明，紧跟着关键字后面是参数类型，接着就当前的参数名称了，我们还可以在参数名后添加对参数的描述，如果想使这些更具可读性，可以在描述前面加上连字符把参数和描述分隔开：

/**
 * @param {Object} param1 - param1 description
 * @param {String} param2 - param2 description
 * @param {Number} param3 - param3 description
 * @param {Array} param4 - param4 description
 */

如果你觉的这样还是没有达到你的期望，可能由于参数名称长短不一，参数类型的字符数也长短不一，你可以试试下面这样：

/**
 * @param {Object} param1                                               param1 description
 * @param {String} paramTwoName                                         param2 description
 * @param {Number} param3                                               param3 description
 * @param {Array} paramFourName                                         param4 description
 */

如果参数是Object类型的，我们可以把这个参数的属性也列出来，像这样：

/**
 * @param {Object} param1                                               param1 description
 * @param {Object} param1.attr1                                         attr1 description
 * @param {String} param1.attr1.endAttr                                 endAttr description
 * @param {Number} param1.attr2                                         attr2 description
 * @param {String} param1.attr3                                         attr3 description
 */

也可以列举数组类型参数的元素：

/**
 * @param {Array.<{name: String, size: Number}>} param1                 param1 description
 * @param {Array.<{String>} param2                                      param1 description
 */

如果有些参数是可选的，我们只需把对应的参数包到一对中括号里：

/**
 * @param {Object} param1                                               required param
 * @param {Object} [param1.attr1]                                       optional attr
 * @param {String} param1.attr2                                         required attr
 * @param {String} [param2]                                             optional param
 * @param {String} param3                                               required param
 */

上面这个例子中，param1、param1的attr2、param3均为必须的参数/属性，param1的attr1和param2为可选的参数/属性

那么如果某个参数的类型不确定或可能是字符串也可能是数字呢，可以这样写：

/**
 * @param {*} param1                                                    this param type can be any type
 * @param {String|Number} param2                                        this param type can be string or number
 */

param1的类型可以是任何类型，param2的类型可以是字符串或数组，当然你也可以添加更多的类型，只需用竖线把各个类型名称隔开

函数返回值

语法

/**
 * @returns type description
 */

声明返回值使用@returns关键字，后面紧跟返回值类型，接着就是返回值的描述，下面是一个示例：

/**
 * @returns {Array|Number} test function returns
 */
function testFunction () {
    const a = 5,
        b = [];
    return Math.random() > 0.5 ? a : b;
}

上面这个函数的返回值是一个数组或者一个数字

生成文档

像文章开始部分，直接jsdoc target_js_file就可以生成jsdoc的文档了，如果jsdoc只是安装在本地，进入到node_module同级目录中，然后执行node ./node_modules/jsdoc/jsdoc.js target_js_file即可

在项目中配置

在项目根目录下创建一个.jsdoc.json文件，并写入以下代码内容：

{
    "tags": {
        "allowUnknownTags": false
    },
    "source": {
        "include": [
            "modules/",
            "package.json",
            "README.md"
        ],
        "includePattern": ".server.controller.js$",
        "excludePattern": "(node_modules/|docs)"
    },
    "plugins": [
        "plugins/markdown",
        "plugins/summarize"
    ],
    "opts": {
        "template": "node_modules/docdash/",
        "encoding": "utf8",
        "destination": "docs/",
        "recurse": true,
        "verbose": true
    },
    "templates": {
        "cleverLinks": false,
        "monospaceLinks": false
    }
}

说明：

allowUnknownTags设置是否允许自定义标签，如果设置成false但使用了自定义标签，在生成文档的时候回报错
include设置目标文件的目录
includePattern设置为哪些文件生成doc，在这里我匹配了所有后缀名为.server.controller.js的文件
excludePattern不包含哪些文件/文件夹
plugins使用的插件集合
template设置模板位置，我这里使用了docdash风格的模板，当然不设置也可以，有默认的模板
encoding输出文件的编码格式
destination输出文档目录
recurse是否地柜查找目标文件，如果设置成true，则则JSDoc将搜索10级深度的文件，如果想要更改搜索深度，在json根节点添加recurseDepth属性并设置一个数字类型的值来声明搜索深度
verbose是否将编译的详细信息输出到控制台
cleverLinks如果testlink是一个URL，那么{@link testlink}将以普通字体呈现，否则就是等宽字体
monospaceLinks链接的字体是否是等款字体，如果cleverLinks设置成true，那么monospaceLinks的值将被忽略

接下来在package.json中加入一条生成文档的命令

{
    ...
    "scripts":{
        "mkdoc": "node_modules/.bin/jsdoc --configure .jsdoc.json"
    }
    ...
}

执行npm run mkdoc就会生成项目文档了，注意我这里使用的jsdoc是本地安装的jsdoc包，并不是全局安装的，这样做的目的是因为如果其他项目组成员想在他本地生成文档可能会忘了安装jsdoc以及其它的一些包。所以我就把jsdoc相关的包放到了开发依赖中。进入到doc文件夹，用浏览器打开index页面，就可以看到相应的文档了