jsDoc注释规范 |
您所在的位置：网站首页 › 前端注释规范有哪些类型的文件 › jsDoc注释规范 |
|
jsDoc，顾名思义，jsDoc是一个用于JavaScript的API文档生成器，类似于Javadoc或phpDocumentor。它根据JavaScript文件中的注释信息，生成JS应用程序或模块的API文档。通过使用JSDoc标记如：命名空间，类，方法参数等，从而使开发者能够轻易地阅读代码，掌握代码定义的类和和其属性和方法，从而降低维护成本并提高开发效率。 JSDoc中文文档 JSDoc官网 JSDoc注释通常应该放在代码被记录之前。为了被JSDoc解析器识别，每个注释必须以/**序列开头,以便由JSDoc解析器识别。 /** ** 这是一段简单的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); } param {object} book : 这样我们在使用book的使用就会提示出所有的属性和方法！ 1.3 @return 返回值注释表示一个函数 的返回值，如果函数没有显示指定返回值可以不写。用法与@param类似，区别在于return只有一个，所以不用指定参数名。 /** * @return {Number} 返回值描述 */ function test () { } // 函数返回 Promise 实例的情况可以这么指定类型 /** * @return {Promise} */ 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/defaultopts.encoding 读取文件的编码，默认是 utf8opts.destination 生成文档的路径，默认是 ./out/opts.recurse 运行时是否递归子目录opts.verbose 运行时是否输出详细信息，默认是 false 2.3 主题及模板1、JSDoc默认的主题有点凌乱，可以通过安装新的主题来配置.常见主题有docdash、minami # 安装 npm install docdash -D # 在jsdoc.json中配置 { "opts" :{ "template":"node_modeules/docdash } }2、如果主题不满意还可以用自己的模板 { "templates": { "cleverLinks": true, "default": { "layoutFile": "plugins/layout.tmpl" } } } |
今日新闻 |
点击排行 |
|
推荐新闻 |
图片新闻 |
|
专题文章 |
| CopyRight 2018-2019 实验室设备网 版权所有 win10的实时保护怎么永久关闭 |