jsdoc -ag凯发k8国际

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或者其他框架中.这样直接用肯定是不行的, 肯定有专门的插件可以配套使用, 随便搜了下,是有的,多多推荐.

总结

以上是ag凯发k8国际为你收集整理的jsdoc --js api文档生成器的全部内容，希望文章能够帮你解决所遇到的问题。

如果觉得ag凯发k8国际网站内容还不错，欢迎将ag凯发k8国际推荐给好友。