ES6写JSDoc的一些经验和实例
ES6写JSDoc的一些经验和实例
关于JSDoc和它的基本语法支持,请参考官方文档:http://usejsdoc.org/。虽说官方文档还是比较全的,实际使用中还是需要摸索一下适合自己项目的写法,并考虑最终文档生成工具的支持。
例1:Object类型在function中的定义
假设我们有个需要Object参数的方法。可以这样写:
/*** 把两个数字a和b加起来* @param {Object} args* @prop {number} [args.a] 我是a* @prop {number} [args.b=0] 我是b,默认值为0* @return {number} 返回a+b*/
function func({ a, b = 0 }) {return a + b;
}
这种写法不允许其他部分重复利用args的结构。
也可以将args独立声明成一个类型:
/*** @typedef {Object} FuncArgs* @prop {number} [a] 我是a* @prop {number} [b=0] 我是b,默认值为0*/
/*** 把两个数字a和b加起来* @param {FuncArgs} args* @return {number} 返回a+b*/
function func({ a, b = 0 }) {return a + b;
}
这种写法通常用于声明全局或模块通用的类型。
也可以将FuncArgs声明为func的内部类型:
/*** @typedef {Object} func~FuncArgs* @prop {number} [a] 我是a* @prop {number} [b=0] 我是b,默认值为0*/
/*** 把两个数字a和b加起来* @param {func~FuncArgs} args* @return {number} 返回a+b*/
function func({ a, b = 0 }) {return a + b;
}
这种写法与同样是为func内部类型的第一种写法比起来,更具可读性。但有个个人不太喜欢的地方就是最终生成的文档会将function和参数的类型分成两个部分,对阅读这种文档结构不熟悉的人来说不是很友好。
例2: function作为参数传入的写法
首先,官方设定了一个@callback
关键字:
/*** @param {func~myCallback} cb* @param {number} num* @return {number}*/
function func(cb, num) {return cb(num);
}
/*** @callback {Function} func~myCallback* @param {number} a* @return {number}*/
不过同例1一样,也可以利用@typedef
关键字:
/*** @param {func~myCallback} cb* @param {number} num* @return {number}*/
function func(cb, num) {return cb(num);
}
/*** @typedef {Function} func~myCallback* @param {number} a* @return {number}*/
这两种基本上是一样的,使用@callback
更符合语义。另外一点是,这种回调方法一般很少通用,所以建议声明为调用方法的内部类型。
例3: ES6模块default export
/** @module testmodule */
/*** @param {number} a I am argument a.* @return {string} Return description.**/
export default function(a, b) {return '' + a + b;
}
jsdoc-to-markdown生成结果:
使用@alias
:
/** @module testmodule */
/*** @alias module:testmodule* @param {number} a* @return {string} b**/
function test(a, b) {return '' + a + b;
}export default test;
jsdoc-to-markdown生成结果跟上面一样。
有趣的是,如果直接export的不是匿名方法,结果会不一样。
/** @module testmodule */
/*** @param {number} a I am argument a.* @return {string} Return description.**/
export default function test(a, b) {return '' + a + b;
}
jsdoc-to-markdown生成结果:
例4: 有多个export的ES6模块
jsoc-to-markdown的wiki给了一个非常简单的例子,但只处理了整个文件没有default export的情况: https://github.com/jsdoc2md/jsdoc-to-markdown/wiki/How-to-document-an-ES2015-module-(multiple-named-exports)。
假设有一个ES6文件:
/** @module testmodule */
/*** @const*/
export const testConst = 1;/*** @enum*/
export const testEnum = {'JS': 1,'PYTHON': 2,'C++': 3
};/*** Function export*/
export function func() {}/*** @param {number} a I am argument a.* @return {string} Return description.**/
export default function test(a, b) {return '' + a + b;
}
生成结果如下:
这就让人很不解了,为啥要把那些跟default无关的东西放在default下面,混淆视听。
但如果把default export去掉就好了:
但现实是这两种有可能同时出现,我没有找到很好的解决办法,目前只能通过避免出现这种写法或者手动加@memberof module:testmodule
,或者更改文档生成模版来修正。
## 例5: 使用Babel
JSDoc还不能聪明到解析ES6代码,为了能让它解析ES6,需要借助于Babel,和插件jsdoc-babel,当然还有相应的Babel preset和插件。
首先安装这些依赖:
npm i --save-dev babel-core babel-preset-env jsdoc jsdoc-babel
然后需要一个JSDoc配置文件, .jsdoc.json(随便什么名字):
{"plugins": ["node_modules/jsdoc-babel"]
}
还要一个.babelrc,根据自己的代码来选择preset和插件:
{"presets": [["env",{"targets": {"browsers": ["last 2 versions", "safari >= 7"]},"modules": false}]]
}
然后运行:
npm run jsdoc -c .jsdoc.json
其他一些状况
有时候模块下的export会被认作内部对象,而不是静态对象
并不是很清楚具体的触发时机,可能是个bug?碰到这种我只能认命加/** @static */
来修正结果。
要选对模版
用ES6写JS最大的好处恐怕就是从此多了无数个文件,每个文件里都只是很小一块代码,从此找代码要靠IDE跳转或全文搜索了。So我会希望将一个文件夹作为一个模块,所有此文件夹下的文件通过index.js来选出该模块开放给别人用的东西。
然后我就发现用JSDoc生成文档的时候,要做到这点比较难。
第一是JSDoc似乎并不能识别文件路径,如果要将多个文件声明属于同一个模块,只有在每个文件头部手动加上/** @module ModuleName */
。
但这一切,还需要模版的帮忙。我试用了nijikokun/minami和tui.jsdoc-template。tui.jsdoc-template很好的实现了我想要的这种树状的结构效果:
还有要考虑的一点是/** @enum */
这个关键字,个人认为是应该要在生成文档时列举出声明的键和值的。但同样的,要看模版支不支持。
支持flow
flow的支持也是简单地靠Babel插件transform-flow-strip-types来完成。
特地拿出来讲是因为我曾很美好地设想可以直接在flow type的声明下面,加上结构特别类似的JSDoc和必要的描述说明文字。把flow type声明转成JSDoc这一步甚至可以完全通过脚本自动完成,会省不少力气。
结果发现如果一个文件纯粹只有flow声明和注释,transform-flow-strip-types这个插件会直接将整个文件的内容干掉,导致里面的JSDoc丢失。
然后flow type声明转成JSDoc这个我刚开始就放弃了,要做到这点我需要一点点分析AST结构,将每种情况对应成JSDoc,很费力而且价值不是很大。
ES6写JSDoc的一些经验和实例相关推荐
- 使用ES6写更好的JavaScript
使用 ES6 写更好的 JavaScript part I:广受欢迎新特性 介绍 在ES2015规范敲定并且Node.js增添了大量的函数式子集的背景下,我们终于可以拍着胸脯说:未来就在眼前. - 我 ...
- python编写一个软件-python写一个随机点名软件的实例
最近有个随机点名软件的需求,故写了一个,上代码:github地址 # -*- coding: utf-8 -*- # @Time : 18-12-31 下午4:21 # @Author : Felix ...
- python制作贪吃蛇游戏_用Python写贪吃蛇游戏的代码实例
这篇文章主要为大家详细介绍了Python贪吃蛇游戏的编写代码,具有一定的参考价值,感兴趣的小伙伴们可以参考一下 最近在学Python,想做点什么来练练手,命令行的贪吃蛇一般是C的练手项目,但是一时之间 ...
- js上拉加载ajax数据,原生ajax写的上拉加载实例
上拉加载的思路 1 上拉加载是要把屏幕拉到最底部的时候触发ajax事件请求数据 2.所有要获取屏幕的高度 文档的高度 和滚动的高度 下面的代码是已经做好了兼容的可以直接拿来用 Javascript: ...
- 怎么用python制作随机点名软件_python写一个随机点名软件的实例
最近有个随机点名软件的需求,故写了一个,上代码:github地址 # -*- coding: utf-8 -*- # @Time : 18-12-31 下午4:21 # @Author : Felix ...
- 核烧写及UBOOT调试经验总结
在某项目经历了内核移植的全过程 某项目沿用FORLINX开发板的uboot及内核版本,项目整体版本虽然稳定但比较旧,在调试过程中遇到不少困难,就本次CID项目内核烧写及UBOOT调试经验总结如下: 一 ...
- python写软件实例-python写一个随机点名软件的实例
最近有个随机点名软件的需求,故写了一个,上代码:github地址 # -*- coding: utf-8 -*- # @Time : 18-12-31 下午4:21 # @Author : Felix ...
- es6 三点运算符_基于es6三点运算符的使用方法(实例讲解)
先看一个es6规范下三点运算符的使用实例: let fun=function(a,...list){ console.log(a,list); }; fun('0','a','b','c');//0 ...
- 面试IT公司的时候,Java程序员的简历应该写多少个项目经验比较合适?
往期精选 ● 架构师高并发高性能分布式教程(4000G) ● 39阶段精品云计算大数据实战视频教程 ● 互联网技术干货视频教程大全[菜单为准] ● 2017年8月最新Intellij IDEA ...
最新文章
- Qt中文手册 之 QTableWidgetItem
- AutoX“真无人”车队驶上繁忙街头,中国正式跨入无人驾驶时代
- 菜鸟之2011-2012学年总结
- html表单复选框样式,美化表单——自定义checkbox和radio样式
- 前端学习(3314):提取action
- 【ACL2020】Relabel the Noise: Joint Extraction of Entities and Relations via Cooperative Multiagents
- 开源的python机器学习模块
- verilog学习记(快速入门)
- 【转载】Java 对象之死
- property_自己编写一个读取Property文件的Util类
- 改变TMQQ2009版消息提示音
- MacOS 10.14.5单双面打印设置
- Python爬虫下载喜马拉雅音频文件
- 2022全新彩虹商城知识付费模板源码+修复改良版
- win10企业版如何安装应用商店-默认没有应用商店
- 重庆大学计算机学院专硕分析,重庆大学电子信息(专硕)专业考研难度分析-专业排名-难度大小...
- 新版标准日本语中级_第二十六课
- 齐岳提供AIE分子N-苄基-4-溴-1, 8-蔡酰亚胺,近红外发射的BODIPY-PhOSi和BODIPY-DMA,超分子聚合物PNA-GBP·I2的合成
- 思维导图软件 XMind 2022
- 手机卡服务器密码忘记了怎么修改密码,wifi密码忘记了怎么办找回密码 手机怎么修改自家wifi密码...
热门文章
- ajax 学习第四天
- 音视频之AudioTrack的使用
- 2021.11.11
- GDOI2007模拟-打鼹鼠
- c语言程序代码中的间隔,printf()函数输出后 默认的间隔是多少
- 【宇宙编码】厉害,生日那天:程序员小哥把天上的宇宙星云都送给女神了~
- win10 Telnet服务器 解决telnet正在连接127.0.0.1...无法打开到主机的连接 在端口 23: 连接失败
- 首席工程师揭秘:LinkedIn大数据后台是如何运作的
- wamp环境下如何安装composer?
- 虚拟化技术详解——少年想自己做个虚拟机吗?