jsdoc 学习笔记

需要配置 jsdoc.json

// 例子
{
  "plugins": ["plugins/markdown"],
  "source": {
      "include": [""],
      "includePattern": ".js$",
      "excludePattern": "(node_modules/|docs)"
  },
  "sourceType": "module",
  "templates": {
      "cleverLinks": true,
      "monospaceLinks": true
  },
  "opts": {
      "recurse": true,
      "destination": "./docs/"
  }
}

生成文档

jsdoc xx.js -c jsdoc.json

如何注释

普通变量

/**
 * 标题文本
 * @param {类型定义}
 */

@param

如果是对象的话可以定义属性 @property
写法类比 @param

@global 记录一个全局对象

类

/**
 * @class
 */

@class

@access private 等价于 @private;
@access protected 等价于 @protected;
@access public 等价于 @public;

@arguments / @extends 指明子类继承自哪个父类。

函数

/**
 * 函数标题文本
 * @param {类型定义} 参数名 参数描述
 * @param {类型定义} [参数名] 参数描述 []表示可选
 * @returns {返回类型} 描述
 */

@param
@returns

如果参数是对象
可以依次注释各个对象的属性

@constructor 声明构造函数

定义类型 （ts 中 type 的思路相同）

@typedef

/**
 * 标题文本
 * @typedef {类型定义} 类型名
 */

定义回调函数 @callback

/**
 * @callback xxXx
 * @param {xxx} xx

添加实例

@example 例子

添加链接

注释文本中可以使用 {@link Xxxx} 来设置跳转到类型、对象；
{@tutorial 向导文件名} 跳转到向导文件；

辅助信息

@author 作者
@since 创建时间
@copyright 记录版权信息
@version 版本信息

---

文件头部

模块可以注释 @module 模块名

/**
 *
 * @file 文件描述
 * @author 作者
 * @see <a href="">xxx</a>
 */ 

---

vue-docgen-api