JSDoc 是一个JavaScript的API文档生成器. 他可以让开发者在开发的过程中, 将编写的注释通过JSDoc工具生成一个api文档, 妈妈再也不用担心我不会写接口文档了.
这里是原作者GitHub项目的地址:链接
1.少废话先看东西
先看一下效果图吧:
/*** @file 这是一个jsDoc的测试demo* @author walker* @version 0.0.1*/
这是对整个js文件的描述
还有一些js文件中函数的效果图:
看了效果图,想必大概也了解这个工具究竟是用来做什么的,虽然界面没有那没漂亮,但整齐还是有的.
2.JSDoc的安装及使用
node不用说, 肯定是必备的. 项目作者还说了:"JSDoc支持稳定版本的Node.js 8.15.0及更高版本。您可以在全局或项目的node_modules文件夹中安装JSDoc ".
1) 新建一个项目, 在项目目录下初始化一下npm
npm init
2) 命令行装 JSDoc
// 先在全局安装
npm install -g jsdoc
// 当前项目安装
npm install --save-dev jsdoc
3) 新建一个要被编译的js文件
demo.js就是这个名字没错了
/*** @file 这是一个jsDoc的测试demo* @author walker* @version 0.0.1*//*** @description Book类, 代表一个书本* @param {string} title - 书本的标题.* @param {string} author - 书本的作者.*/
function Book(title, author) {this.title = title;this.author = author;
}
Book.prototype = {/*** @description 获取书本的标题* @returns {string|*}*/getTitle: function () {return this.title;},/*** @description 设置书本的页数* @param pageNum {number} 页数*/setPageNum: function (pageNum) {this.pageNum = pageNum;}
};/*** @description 这是一个有返回值得求和函数* @param {*} num1 加数* @param {*} num2 被加数* @returns {num|*} myTestVal 两数之和 */
var myTest2 = function (num1, num2) {var myTestVal;myTestVal = num1 + num2;return myTestVal;
}
myTest2(2, 2)/*** @description num2是一个没用的变量*/
var num2 = 2;// @description num是两数之和
var num;
/*** @description 这是一个没有返回值求和的函数* @param {*} num1 加数* @param {*} num2 被加数*/
var myTest = function (num1, num2) {num = num1 + num2;
}
myTest(1, 2)var testVal;
/*** @description 这是一个没有参数的函数*/
function test() {console.log("123")
}
4) 命令行编译文件:
jsdoc demo.js
5) 编译成功
编译成功后就会看到目录下多了一个out目录, 点击index.html从浏览器打开m, 就会看到上面的效果图了
3.下面介绍一些常见的JSDoc注释符
| 标签 | 描述 | 示例 |
|---|---|---|
| @file | 文件描述。也可写作@overview或者@fileoverview | @file description |
| @author | 指明作者 | @author description |
| @version | 指定类的版本 | @version info |
| @class | 指明类名，也写作@constructor | @class class name or function name |
| @description | 描述当前函数或者类的作用，也可写作@desc | @description functions |
| @param | 说明一个方法的参数，通常需要用{}指明数据类型 | @param {String} parameter name |
| @returns | 说明返回值类型，用{}指明返回值数据类型 | @returns {String} explanation |
| @type | 指定函数的返回类型 | |
| @deprecated | 指明一个过期的类或成员 | @deprecated description |
| @see | 指定一个到另一个主题的链接 | @see anchor |
| @extends | 指示一个类派生了另一个类。JSDoc通常自己就可以检测出这种信息，不过，在某些情况下则必须使用这个标 | |
| @exception | 标志一个类抛出的异常 | @exception exception-name explanation |
| @throws | 和 @exception标签一样. | The @throws tag has the same meaning as the @exception tag. |
| {@link} | 插入一个到另一个主题的链接 | {@link name text} |
| @since | 标记当引入一个特定的变化时 | @since release |
| @final | 指示一个值是常量值. 记住JavaScript无法真正保证一个值是常量 | Constant value |
| @ignore | JSDoc忽略有这个标记的函数 |
ps:单行注释”//”不会被编译.
如果只想对函数进行描述,”//@description Book类, 代表一个书本”, 这样写是不行的,必须使用/** */注释
还有一些文档,详情请看链接
JSDoc3常用标签使用说明+示例: https://www.jianshu.com/p/c190dc9dd0d5
JSDoc在线手册：http://www.dba.cn/book/jsdoc/
JSDoc3: https://github.com/jsdoc/jsdoc
JSDoc英文手册：https://jsdoc.app/
JSDoc 注释规范：https://www.cnblogs.com/Garven/articles/7161797.html
最后:其实这只是传统项目的用法,在vue或者其他框架中.这样直接用肯定是不行的, 肯定有专门的插件可以配套使用, 随便搜了下,是有的,多多推荐.