五分钟玩转文档化工具JSDuck


声明:本文转载自https://my.oschina.net/lsjcoder/blog/1583072,转载目的在于传递更多信息,仅供学习交流之用。如有侵权行为,请联系我,我会及时删除。

字数:981

阅读时间:5分钟

选型依据


​ 在经历了数个上线的项目之后,笔者所在的团队已经沉淀了一个相对稳定版本的前端框架。因此,我们需要出具一套框架API文档,以便公司其他成员的使用和框架的后期维护。我们在对现在较主流的五个文档工具:JSDoc 3、YUIDoc、Dox、Docco、JSDuck分别作了调研和尝试,得到结论如下:

工具优点缺点
JSDoc3提供了完整的模板开发、事件触发等接口,使用非常灵活。对代码要求比较严格,学习曲线较高。
YUIDoc不止支持JS语言,更加抽象,如果同时使用了 Ruby/PHP/Python等语言YUI都可以使用。功能更加抽象,具体实现方面考虑不全。
Dox轻量级、高度可定制化,兼容JSDoc3语法。后期会有较多问题需要自己解决。
Docco行间注释方式,更注重实现过程的文档不太适合API注释
JSDuck代码实时修改、语法灵活、支持MarkDown语法,支持查看源码并且文档可读性较高,最主要的是上手非常快。可定制化支持不足,略显臃肿。

​ 我们选型的条件权重由高到低依次是:

​ 1.较强的可读性。

​ 2.较低的学习成本。

​ 3.注释语义的丰富程度,是否满足我们的需求。

​ 4.是否足够灵活。

​ JSDuck可读性较高,上手较快,并且使用JSDuck工具生成的extJS文档的成功有目共睹,综合考量,我们最终选择了JSDuck工具。

环境部署


​ 由于JSDuck需要依赖ruby环境,所以环境部署分为以下三步:

​ 1.安装ruby

​ 2.安装devkit

​ 3.安装JSDuck

第一步,安装ruby :

​ 下载地址:<https://rubyinstaller.org/downloads/>

图1

​ 选择符合本机电脑的安装包下载即可。

第二步,安装devkit:

​ 下载地址:<https://rubyinstaller.org/downloads/>

图2

​ 选择符合本机电脑的安装包下载即可。注意devkit安装目录不要有中文或者特殊字符,然后在安装根目录下执行cmd命令 ruby dk.rb init。这时,我们会在当前目录下看到一个config.yml文件,编辑该文件,添加ruby目录配置。例如,笔者的ruby是安装在 F:/Ruby22-x64 目录下,就做如下图修改即可:

图3

​ 安装成功后,执行命令 ruby dk.rb install 命令。

第三步:安装JSDuck

​ 执行命令 gem install jsduck 命令安装jsduck。

​ 至此,JSDuck的环境部署已经全部完成了。

第一个文档


​ 准备工作终于做完了,那还等什么,当然是马上开始看看我们成果如何啦!

​ 在 G:\test-jsduck目录下,创建一个test.js文件,编写如下代码:

/**  * @class 人类  * @author lsjcoder  * @docauthor lsjcoder  */ function People(){ 	/** 	 *  	 * @property {String} 姓名 	 */ 	this.name = "lsjcoder";  	/** 	 * 吃饭 	 * @method 	 * @param food {String} 食物名称 	 * @return {Boolean}  是否吃过 	 */ 	this.eat = function(food){ 		if(food != null){ 			return true; 		}else{ 			return false; 		} 	} } 

​ 然后在cmd中运行命令 jsduck "G:\test-jsduck\test.js" --output=G:\test-jsduck\doc ,工具就自动将文档生成到目录 G:\test-jsduck\doc 下,直接运行里面的 index.html 文件就可以看到如下成果图:

图4

​ 是不是非常简单粗暴且可读性爆表呀!笔者会在接下来的系列文章中详细介绍JSDuck的所有技术,并且最后会将笔者公司在JSDuck中前端框架的实践以案例的形式分享给大家,敬请期待哦!

欢迎关注我的微信公众号:

本文发表于2017年12月01日 10:33
(c)注:本文转载自https://my.oschina.net/lsjcoder/blog/1583072,转载目的在于传递更多信息,并不代表本网赞同其观点和对其真实性负责。如有侵权行为,请联系我们,我们会及时删除.

阅读 2041 讨论 0 喜欢 0

抢先体验

扫码体验
趣味小程序
文字表情生成器

闪念胶囊

你要过得好哇,这样我才能恨你啊,你要是过得不好,我都不知道该恨你还是拥抱你啊。

直抵黄龙府,与诸君痛饮尔。

那时陪伴我的人啊,你们如今在何方。

不出意外的话,我们再也不会见了,祝你前程似锦。

这世界真好,吃野东西也要留出这条命来看看

快捷链接
网站地图
提交友链
Copyright © 2016 - 2021 Cion.
All Rights Reserved.
京ICP备2021004668号-1