常见的JavaScript编程开发文档生成工具分享

对于前端编程开发程序员来说，一些提前准备好的开发设计文档能够大大提高我们的工作效率，同时也可以让其他的程序员理解我们的开发思路和目的。下面我们就一起来了解一下，常见的

JavaScript

编程开发文档都有哪些工具。

为什么需要Javascript文档

让前端程序更具可维护性，是一个老生常谈的问题，大多数时候我们都关注于应用层面的代码可维护性，如：OO、模块化、MVC，编码规范、可扩展和复用性，但这都是属于设计层面需要考虑的事情，可维护性还应包含另一个方面，也是很多coder容易忽略的地方，就是将自己写的程序以文档的形式沉淀起来，对自己工作有一个结构化的组织，也可以帮助到他人。

试想一下如下情况：

团队中加入了新的同学，这时他可能需要快速的将目前项目中现有程序有一个系统的了解，如：某个公共工具模块的用途，某个通用组件的接口，程序之间的依赖性，这时他只有去看源码和注释了。

团队中有同学离开，但他写的程序在此之前已经深入到项目的各个层面，了解和能快速修改维护这些程序的人可能只有他，之后在迭代时遇上其环节，其他接手的同学只能望眼欲穿了。

自己写了一个不错的可复用组件，打算推广到团队中，这时他人需要使用自己的组件时不得不去看源码和注释了。

这时候如果每个人都对自己程序有一个文档化的阐释，便可对上述问题做出很大的缓解，通常程序的文档化需求只存在于大型项目或是拥有成熟体系的框架之中，对于前端们来讲其实大多数时候都想用文档来展示和沉淀自己的知识成果的，可一直缺乏一套行之有效快速一致性的解决方案，导致在大家谈到程序文档化的时候都因为时间关系，繁琐程度就望而却步了。

主流的Javascript注释文档生成工具

JSDoc 3

JSDoc 3的前身是JSDoc Toolkit。它会对代码的具体实施进行扫描，因此你如果不按照符合JSDoc的注释语法来进行注释的话，可能生成的文档一个字也没有。虽然它的学习曲线很高，但是一旦掌握了之后，由于它提供了完整的模版开发，事件触发等等接口，其灵活性也是不容小觑的。

YUIDoc

YUIDoc是YUI的附属项目。YUI团队希望这个文档工具不仅仅可以支持Javascript，而是更多的脚本语言，因此它并不考虑实际的代码实施细节，而只是对注释部分进行了扫描。从好的一面来说，如果你同时使用了Ruby/PHP/Python等等，YUI或许是一个比较适合的工具。从反面来说，因为它没有考虑实施细节，你需要额外的变量声明、同时生成的文档有可能会和实际的实施细节不吻合。

Dox

Dox是一个非常轻量级和可以定制化的工具，它使用和JSDoc 3兼容的注释语法标准，并将其转化成JSON格式。因此在呈现方式上具有比JSDoc 3更强的可定制性，当然也意味着你初期的麻烦会比较多。

Docco

Docco是一种行间注释的方式。比起API注释，它更适合于注释代码的实施逻辑，以便于后期程序员能够快速捕捉到原作者在此处的实施意图。应该说是非常适合开源项目、多个作者共同维护的一个文档工具。比如的Backbone Annotated Source就是使用Docco进行注释的。

JSDuck

JSDuck由Sencha开发，因此对于自家extJS具有非常强大的支持功能，包括令人咋舌的实时代码修改。但即使你不是使用extJS进行开发，JSDuck仍然是一个非常强大的工具，一方面它的语法非常灵活，描述支持Markdown语法，上手难度远远低于JSDoc 3;另一方面它生成的文档可读性堪比YUIDoc，同时支持源码的对照，学习起来也非常的容易。要说JSDuck有什么不好的地方，估计就是它把一切都Handle太完美了以致于没有给你提供什么可以自己定制的余地。

作者：梁桂钊

节选：公众号：服务端思维

【免责声明】本文系本网编辑部分转载，转载目的在于传递更多信息，并不代表本网赞同其观点和对其真实性负责。如涉及作品内容、版权和其它问题，请在30日内与管理员联系，我们会予以更改或删除相关文章，以保证您的权益!