文档章节

五分钟玩转文档化工具JSDuck

老司机带你撸代码
 老司机带你撸代码
发布于 2017/11/30 22:30
字数 905
阅读 968
收藏 10

字数: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中前端框架的实践以案例的形式分享给大家,敬请期待哦!

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

© 著作权归作者所有

老司机带你撸代码
粉丝 52
博文 22
码字总数 36413
作品 0
武汉
高级程序员
私信 提问
【CF 应用开发大赛】WeBot - 微信公众平台消息接口类库(nodejs)

应用名称:WeBot - 微信公众平台提供的开放信息接口的自动回复系统,基于node.js 实现。 创新点(亮点): 1. 开源类库,基于node.js,支持快速开发微信公众平台的消息处理后台系统。https:/...

天猪
2013/01/25
4.1K
17
jsduck 生成 doc失败

以上是错误消息,有人弄过嘛 麻烦给一下解决办法是怎么处理的。

噗哈哈哈嗝
09/23
24
0
如何定制jsduck中API Documentation页签下的预览界面?

@大漠穷秋 你好,想跟你请教个问题: 最近在看你总设计负责的Ext中文版API文档,有个问题向您请教:API Documentation页签下的预览界面,标注团队成员信息的部分是如何定制的呢?还恳请您指点...

Su8marine
2017/05/11
71
0
Hadoop 的数据处理解决方案 - Cascalog

Cascalog 是 Hadoop 上的数据处理解决方案,无需 hassle。 Cascalog 是 Clojure 或者 Java 的全功能数据处理和查询库。Cascalog 主要的作用是处理 Hadoop 上的“大数据”或者分析你的本地电脑...

匿名
2014/10/28
845
0
2019年推荐几个你看了就会关注的公众号

大V推荐 作为一个可怜弱小又无助的小萌新,求知若渴却找不到良好的渠道去学习,只能看着教科书苦哈哈的抓瞎学习? 不用担心,这里为大家带来如下几个Python和知乎的大佬们!迷茫的萌新们快扫...

JAVA高级架构v
02/28
0
0

没有更多内容

加载失败,请刷新页面

加载更多

001-ELKStack之Elasticearch

ELKStack 之 Elasticsearch ELK Stack 是 Elasticsearch、Logstash、Kibana 三个开源软件的组合。在实时数据检索和分析场合,三者通常是配合共用,而且又都先后归于 Elastic.co 公司名下,故...

伟大源于勇敢的开始
21分钟前
3
0
Kotlin基础语法学习

安装好安卓studio,以及插件支持Kotlin 就可以在创建项目的时候选择 Kotlin语言了。 https://www.jianshu.com/p/4ab13691d681 参考手册: https://www.runoob.com/kotlin/otlin-android-setu...

T型人才追梦者
今天
6
0
java实现简单计算器

1.概述 之前作者写过一篇文章,也是关于计算器的,用的是C++与Qt,链接在这里 这次用java的swing写的(这差距好像有点大,好吧是qt太强了). 先上图: 2.UI 总体布局使用流布局. (1)文本框 文本框就...

Blueeeeeee
今天
9
0
纯CSS实现DIV悬浮(固定位置)

纯CSS实现的DIV悬浮效果(固定位置),兼容常用的浏览器:IE8、360、FireFox、Chrome、Safari、Opera、傲游、搜狗、世界之窗等。效果如下: 实现代码: <!DOCTYPE html> <html> <head> <meta ...

独钓渔
今天
6
0
OSChina 周二乱弹 —— 给我来个女菩萨

Osc乱弹歌单(2019)请戳(这里) 【今日歌曲】 @这次装个文艺青年吧 :#今日歌曲推荐#分享XXXTENTACION/Travis Barker的单曲《Pain = BESTFRIEND》: 《Pain = BESTFRIEND》- XXXTENTACION/...

小小编辑
今天
159
4

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部