使用jsDoc(注释规范)

jsDoc,顾名思义,jsDoc是一个用于JavaScript的API文档生成器,类似于Javadoc或phpDocumentor。它根据JavaScript文件中的注释信息,生成JS应用程序或模块的API文档。通过使用JSDoc标记如:命名空间,类,方法参数等,从而使开发者能够轻易地阅读代码,掌握代码定义的类和和其属性和方法,从而降低维护成本并提高开发效率。
JSDoc中文文档
JSDoc注释通常应该放在代码被记录之前。为了被JSDoc解析器识别,每个注释必须以/**序列开头,以便由JSDoc解析器识别。

/**
** 这是一段简单的JsDoc注释。
*/

在WebStorm启用JSDoc方法

  • 在函数附近输入/** 并按回车键 ,添加函数说明、参数类型和说明及返回值类型和说明
  • 按下快捷键 ctrl+shift+A ,在弹出的输入框中输入Fix Doc Comment, 选中Fix Doc Comment并回车即可;

在vscode中启用JSDoc方法

  • 由于VS Code内置了JSDoc支持,在输入/**后就会触发语法提示 

一、常用注释规范


1.1 @constructor 构造函数声明注释

     @constructor明确一个函数 是某个类的构造函数

1.2 @param 参数注释

     通过@param来表示函数、类的方法的参数。@param是最常用的注释标签。参数标签可表示 一个参数的参数名、参数类型和参数描述的注释。通过参数注释,可以在vscode中联想出相应的参数类型,让开发更便捷。如:

/**
* 表示一本书
* @constructor
* @param {string} title - 书名
* @param {string} author - 作者
*
*/
function Book(title,author){}

let book = new Book('aaa','bbb')
  • param {string} title : 表示给参数title增加一个string类型。这个类型可以是string,number,boolean这类基础数据类型,也可以是复杂数据类型如object
/**
 * 
 * @param {Object} book 
 * @param {string} book.title
 * @param {string} book.author
 */

function buyBook(book) {    }

// 数组参数
/**
 * Assign the project to a list of employees.
 * @param {Object[]} employees - The employees who are responsible for the project.
 * @param {string} employees[].name - The name of an employee.
 * @param {string} employees[].department - The employee's department.
 */
Project.prototype.assign = function(employees) {
    // ...
}; 

// 可选参数
/**
 * @param {string} [somebody] - Somebody's name.
 */
function sayHello(somebody) {
    if (!somebody) {
        somebody = 'John Doe';
    }
    alert('Hello ' + somebody);
} 
1.3 @return 返回值注释

表示一个函数 的返回值,如果函数没有显示指定返回值可以不写。用法与@param类似,区别在于return只有一个,所以不用指定参数名。

/**
* @return {Number} 返回值描述
*/
function test () { }

// 函数返回 Promise 实例的情况可以这么指定类型
/**
 * @return {Promise<number>}
 */
function testPromise () {
  return new Promise((res) => {
    res(1)
  })
}
1.4 @example 示例注释

用于表示示例代码,通常示例的代码会另起一行编写

/**
* @author Mondo 
* @description list 数据结构 转换成 树结构
* @param {Array} data 需要转换的数据
* @param {String} id 节点 id
* @param {String} pid 父级节点 id
* @param {String} child 子树为节点对象的某个属性值
* @param {Object} labels 需要新增的字段名集合 { label: 'category_name' }
* @return {Array}
*
* @example
* formatListToTree({data: [{id:1}, {id: 2}, {id: 3, pid: 1}]})
* =>
* [ { id: 1, children: [ {id: 3, pid: 1} ] }, { id: 2 } ]
*/

function formatListToTree({
  data = [],
  id = "id",
  pid = "pid",
  child = "children",
  labels = null
}) {
...
}

  • @author 该类/方法的作者。
  • @class 表示这是一个类。
  • @function/@method 表示这是一个函数/方法(这是同义词)。
  • @private 表示该类/方法是私有的,JSDOC 不会为其生成文档。
  • @name 该类/方法的名字。
  • @description 该类/方法的描述。
  • @param 该类/方法的参数,可重复定义。
  • @return 该类/方法的返回类型。
  • @link 创建超链接,生成文档时可以为其链接到其他部分。
  • @example 创建例子。
1.5 @typedef和@property 自定义类型

使用@typedef和@property 定义一个类型,然后在其他地方使用

/**
* @typedef {Object} Book
* @property {string} title 书名
* @property {string} author 	作者
*/

/**
* @param {Book} bo 要收藏的书对象
*/
function collectBook(bo){}
1.6 文件注释
/**
 * @file  jsdoc测试文件
 * @author wujing
 * @copyright no
 * @createDate 2022-05-07 16:22
 */
1.7 变量注释
/**
 * @var {object}
 * @desc 变量定义
 * @property {string} a 属性a
 * @property {string} b 属性b
 */

 var foo = {
     a: 'a',
     b: 'b'
}

1.8 常量注释
/**
 * 
 * @constant {string}
 * @default #000
 * @desc 颜色定义
 */
const COLOR_WHITE = '#FFF';

1.9 方法注释
/**
 * @methor 
 * @param {Type} data={} 目标对象
 * @example 
 * {
 *      target: 手机号
 * }
 * @return {Type} 运营商名称
 * @desc 根据目标对象获取运营商
 *
 */
function matchNumber(data){
    return '返回对象'
}
1.10 回调函数
/**
 * This callback type is called `requestCallback` and is displayed as a global symbol.
 *
 * @callback requestCallback
 * @param {number} responseCode
 * @param {string} responseMessage
 */
/**
 * Does something asynchronously and executes the callback on completion.
 * @param {requestCallback} cb - The callback that handles the response.
 */
function doSomethingAsynchronously(cb) {
    // code
}; 

二、通过JSDoc生成文档网站

类似于我们平常对接口用到的swagger一样,借助JSDoc也可生成类似网站

2.1 安装

# 全局安装
npm install jsdoc -g
# 或者 局部安装
npm install jsdoc -save-dev

2.2 使用
1、基本使用

运动命令后,默认生成out文件夹,包含编译后的文档(html)部署后即可通过文档来看各文件方法说明

jsdoc a.js b.js ...
2、配置使用

在项目下定义 jsdoc.json 配置文件,通过 -c 参数来指定

# 方式一:生成配置文件
jsdoc -c jsdoc.json

# 方式二: 在package.json中的scripts添加命令。 这样通过npm run docs即可生成文档
{
	"scripts": {
  	"docs": "jsdoc -c jsdoc.json"
  }
}

3、配置文件
{
  "source": {
    "include": [ "src/" ],	
    "exclude": [ "src/libs" ]
  },
  "opts": {
    "template": "templates/default",
    "encoding": "utf8",
    "destination": "./docs/",
    "recurse": true,
    "verbose": false
  }
}

  • source 表示传递给 JSDOC 的文件
  • source.include 表示 JSDOC 需要扫描哪些文件
  • source.exclude 表示 JSDOC 需要排除哪些文件
  • opts 表示传递给 JSDOC 的选项
  • opts.template 生成文档的模板,默认是 templates/default
  • opts.encoding 读取文件的编码,默认是 utf8
  • opts.destination 生成文档的路径,默认是 ./out/
  • opts.recurse 运行时是否递归子目录
  • opts.verbose 运行时是否输出详细信息,默认是 false
2.3 主题及模板

1、JSDoc默认的主题有点凌乱,可以通过安装新的主题来配置.常见主题有docdashminami

# 安装
npm install docdash -D

# 在jsdoc.json中配置
{
  "opts" :{
    "template":"node_modeules/docdash
  }
}

2、如果主题不满意还可以用自己的模板

{
  "templates": {
    "cleverLinks": true,
    "default": {
      "layoutFile": "plugins/layout.tmpl"
    }
  }
}

  • 1
    点赞
  • 5
    收藏
    觉得还不错? 一键收藏
  • 0
    评论

“相关推荐”对你有帮助么?

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值