文档生成工具
该工具库是对jsdoc以及jsdoc模板--docdash的封装
使用说明
- npm install -g youpin-lib-doc
- 项目目录执行ypldoc entry output > error.txt 2>&1
- entry默认src/,output默认out/
- 建议执行命令加上后面的命令生成错误文件,方便注释语法的错误查看
- 文档的首页为当前项目的README.md
- 如需替换默认参数,在本地自行编写jsdoc.json,参考jsdoc文档和docdash文档
注释编写
- 文档生成采用了JSDoc,注释一般应该放置在方法或函数声明之前,它必须以/ **开始,以便由JSDoc解析器识别。其他任何以/*,/***或者超过3个星号的注释,都将被JSDoc解析器忽略。例如以下代码:
/**
* Book类,代表一个书本.
* @constructor
* @param {string} title - 书本的标题.
* @param {string} author - 书本的作者.
*/
- JSDoc通过分析你的代码会自动识别类和它们的构造函数,class会自动被分出来一类
- 常见的分类还有
@module @mixin
,没有特殊定义的export的变量和方法归为global - 其他标签参考使用说明的文档
常见错误
ERROR: The @returns tag requires a value
, @returns块标签后一定要跟返回值类型ERROR: Unable to parse a tag's type expression...
/**
* 修改商品数量
* @param itemId
* @param num 修改的数量
* @param editStatus:0 可以编辑, 1 编辑中
* @param pigeon "{spm:'',scm:'',iid:''}" 打点数据 字符串
*/
@param pigeon "{spm:'',scm:'',iid:''}" 打点数据 字符串,包含了参数名称、参数的值及类型、参数说明,其中,"{spm:'',scm:'',iid:''}" 无法识别,可以使用以下方式来描述对象参数及他的值:
/**
* Assign the project to an employee.
* @param {Object} employee - The employee who is responsible for the project.
* @param {string} employee.name - The name of the employee.
* @param {string} employee.department - The employee's department.
*/
- @param的书写方法
- @type的书写方法