背书
JSDoc是一个根据javascript文件中注释信息,生成JavaScript应用程序或库、模块的API文档 的工具。你可以使用他记录如:命名空间,类,方法,方法参数等。类似JavaDoc和PHPDoc。现在很多编辑器或IDE中还可以通过JSDoc直接或使用插件生成智能提示。从而使开发者很容易了解整个类和其中的属性和方法,并且快速知道如何使用,从而提高开发效率,降低维护成本。
JSDoc 示例
JSDoc注释一般应该放置在方法或函数声明之前,它必须以/ **
开始,以便由JSDoc解析器识别。其他任何以/*
,/***
或者超过3个星号的注释,都将被JSDoc解析器忽略。例如一下代码:
/**
* @description 获取产品列表
* @param {String} kind 产品类型
* @param {int} currentPage 当前页
* @param {int} pageCount 每页多少条记录
* @see https://the_wike_url.com
*/
ProductService.prototype.$getProductList = function(kind, currentPage, pageCount) {
kind = kind || 'spirit';
currentPage = currentPage || 1;
pageCount = pageCount || 20;
var url = '/product';
return this.http.$getJson(url, {
kind: kind,
currentPage: currentPage,
pageCount: pageCount
});
};
复制代码
在JSDoc 注释有一套标准的注释标签,一般以@开头
常用的注释标签
(未完待续)
复制代码
JSDoc 安装
npm install jsdoc -g
复制代码
jsdoc 命令
jsdoc.json 配置文件事例
{
"tags": {
"allowUnknownTags": true,
"dictionaries": ["jsdoc","closure"]
},
"source": {
"include": ["index.js", "lib"],
"includePattern": ".+\\.js(doc)?$",
"excludePattern": "(^|\\/|\\\\)_"
},
"plugins": ["plugins/markdown"],
"templates": {
"cleverLinks": false,
"monospaceLinks": false
},
"opts": {
"template": "./node_modules/ink-docstrap/template",
"encoding": "utf8",
"destination": "./out/",
"recurse": true,
"readme": "./README.MD"
}
}
复制代码
执行脚本,指定目录生成文件
# 从项目package.json文件中获取项目版本号
version=`cat package.json | grep version | awk -F \" '{print $4}'`
# 生成jsdoc
jsdoc -c jsdoc.json
# jsdoc文档
source=./out/*
# 分发目录
dist=/var/jsdoc/libname/$version/
# 避免文件夹不存在,强制创建
mkdir -vp $dist
# 将jsdoc文档发布到分发目录
cp -R -f $source $dist
复制代码