jsdoc相关知识

什么是JSDoc

JSDoc是一个针对javascript的API文档生成器。它从javascript程序源代码中抽取类、方法、成员等注释信息形成一个和源代码配套的API帮助文档。类似JavaDoc和PHPDoc。JSDoc工具能扫描你在源代码中添加指定格式的注释，并生成一个API文档网站(即在指定目录下生成相关的网页文件)。此外现在很多编辑器或IDE中还可以通过JSDoc直接或使用插件生成智能提示。从而使开发者很容易了解整个类和其中的属性和方法，并且快速知道如何使用，从而提高开发效率，降低维护成本。
JSDoc生成API文档只是一个方面，其更主要的贡献在于对代码注释格式进行了规范化。

JSDoc的规则

JSDoc注释一般应该放置在方法声明之前，它必须以 / ** 开始，以便由JSDoc解析器识别。其他任何以 /* ， /*** 或者超过3个星号的注释，都将被JSDoc解析器忽略。在JSDoc 注释有一套标准的注释标签，一般以@开头。
常见标签有：
@constructor 明确一个函数是某个类的构造函数
@param 描述一个传递给函数的参数。类型描述不区分大小写，最好大写开头。
类型包括 *, String, Array, Object, Boolean, Undefined, Number, 自定义类型
@returns 描述函数返回值的信息。也可以写成@return
@callback 表明回调函数
@description —— 描述
@example —— 举例
@throws —— 描述可能会被抛出什么样的错误
@version 指定发布版本
@file —— 文件说明，在文件开头使用
@license —— 描述代码才有那种软件许可协议
{@link} ——插入一个到另一个主题的链接,这是行内标签
@todo ——将做的事情

/**
 * @file 这是一个jsDoc的测试demo
 * @author xxx
 * @version 0.0.1
 */

// 方法的描述也可写成 “@description Book类, 代表一个书本”，但一般使用简写，去掉开头的@description
// 如果函数是类的构造函数，则可以通过添加 `@constructor` 标记来指示这一点。
// 参数使用[]包含，表示这个参数可选，可传可不传。如 `@param {string} [b] b是可选参数`
/**
 * Book类，代表一个书本. 
 * @constructor
 * @param {string} title - 书本的标题.
 * @param {string} author - 书本的作者.
 */
function Book(title, author,) {
    this.title=title;
    this.author=author;
}
Book.prototype={
	init
    /**
     * 获取书本的标题
     * @returns {string|*}
     */
    getTitle:function(){
        return this.title;
    },
    /**
     * 设置书本的页数
     * @param pageNum {number} 页数
     */
    setPageNum:function(pageNum){
        this.pageNum=pageNum;
    }
}; 
/**
 * 我的方法
 * @param {string[]} arr 传入的参数是个字符串组成的数组
 * @param {string} [b] -加上连字符便于阅读。使用[]包含b表示这是个可选的参数
 */
 function myFun(arr) {
	
 }

JSDoc的安装使用

1. 安装：可以全局安装，也可以局部安装，即安装到项目里。

全局安装： npm install -g jsdoc
局部安装： npm install --save-dev jsdoc
注意： --save-dev 也可以缩写为 -D，建议使用 --save-dev 本地安装模式
目前版本是JSDoc3，官网https://jsdoc.app/index.html

2. 使用：
   如果有需要，还可以在工程中创建一个JSDoc的配置文件，通常命名为conf.json 或 conf.js，这儿我们直接使用默认配置。
   假设你有一个xx.js的文件，在cmd 中运行 jsdoc XX.js，将解析 xx.js 文件，生成API文档。默认是在当前目录下生成在一个 out 目录，当然你也可以使用 -d 命令指定其他的目录 jsdoc xx.js -d ./api/。使用 -c 命令指定要使用的配置 jsdoc -c /configs/conf.json。

3. jsdoc命令常用选项：
   -c 或 --configure：指定JSDoc配置文件的路径。默认为安装JSDoc目录下的conf.json或conf.json
   -d 或 --destination：指定输出生成文档的文件夹路径。JSDoc内置的Haruki模板，使用console 将数据转储到控制台。默认为 ./out
   -r 或 --recurse：扫描源文件和导览时递归到子目录
   -R 或 --readme：用来包含到生成文档的README.md文件。默认为在源路径中找到的第一个README.md文件
   -t 或 --template：用于生成输出文档的模板的路径。默认为templates/default，JSDoc内置的默认模板
   -v 或 --version：显示jsdoc版本号
   更多选项可通过 -h 或 --help选项查看

4. 默认配置选项：
   如果没有为JSDoc指定配置文件，那么JSDoc将使用下面的默认配置：

{
    "plugins": [],
    "recurseDepth": 10,
    "source": {
        "includePattern": ".+\\.js(doc|x)?$",
        "excludePattern": "(^|\\/|\\\\)_"
    },
    "sourceType": "module",
    "tags": {
        "allowUnknownTags": true,
        "dictionaries": ["jsdoc","closure"]
    },
    "templates": {
        "cleverLinks": false,
        "monospaceLinks": false
    }
}
// 其含义如下：
// 没有拆件被加载 (plugins).
// 如果使用 -r 命令行选项开启了递归支持, JSDoc的递归深度为10 (recurseDepth).
// 仅后缀名为 .js, .jsdoc, and .jsx的文件会被处理(source.includePattern).
// 任何以下划线开始的文件或目录将会被忽略 (source.excludePattern).
// JSDoc 支持使用 ES2015 modules的代码 (sourceType).
// JSDoc 允许你使用未识别的标签 (tags.allowUnknownTags).
// JSDoc 的标准标签 和 Closure Compiler tags都是支持的(tags.dictionaries).
// 内联 {@link} 标签 以纯文本的方式被渲染 (templates.cleverLinks,templates.monospaceLinks).

如何在jsdoc中描述“对象”参数中的属性？

1. 对于具有一组已知属性的对象，可以在该对象的@param标记后立即对其进行记录，该方法不能用于@returns。如下所示：

/**
 * @param {Object} userInfo Information about the user.
 * @param {String} userInfo.name The name of the user.
 * @param {Number} userInfo.age The age of the user.
 */
function logIn(userInfo) {
       doLogIn(userInfo.name, userInfo.age);
}

2. 对于具有一组已知属性的对象，对于不需要进一步描述每个属性的对象，此语法是理想的。它可用于@returns和@param。

/**
 * @param {{a: number, b: string, c}}  myObj  description
 */

3. 对于将在源码中多个点使用的对象，@typedef 非常方便。它可以描述一个自定义类型，再在@param, @returns, @type, @callback 或 其他JSDoc标签中反复引用它。

// typedef的语法：`@typedef [<type>] <namepath>`
/**
 * 这是人这个对象类型的定义
 * @typedef {Object} Person
 * @property {String} name 人的名字
 * @property {Number} age 人的年龄
 */
...
其他地方使用它,
`@param` 标签中使用它
/**
 * @param {Person} p 对于参数p的描述
 */
或`@return`标签中使用它
 /**
 * @returns {Person} 返回值的描述
 */

4. 对于其值均相同类型的对象，该语法可用于@param 和 @returns

/**
 * @param {Object.<string, number>} dict key始终是字符串类型，val始终是数字类型

 */

链接：

1. http://shouce.jb51.net/jsdoc/index.html