生成JS API文档的JSDoc——重写件

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