JSDoc 实践

背书

JSDoc是一个根据javascript文件中注释信息，生成JavaScript应用程序或库、模块的API文档的工具。你可以使用他记录如：命名空间，类，方法，方法参数等。类似JavaDoc和PHPDoc。现在很多编辑器或IDE中还可以通过JSDoc直接或使用插件生成智能提示。从而使开发者很容易了解整个类和其中的属性和方法，并且快速知道如何使用，从而提高开发效率，降低维护成本。

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