文章目录

  1. 1. 为什么需要Javascript文档
  2. 2. 主流的Javascript注释文档生成工具
    1. 2.1. JSDoc 3
    2. 2.2. YUIDoc
    3. 2.3. Dox
    4. 2.4. Docco
    5. 2.5. JSDuck
  3. 3. 我的选择
    1. 3.1. 步骤一:下载文件
    2. 3.2. 步骤二:执行命令
      1. 3.2.1. 常用命令
      2. 3.2.2. 注释语法
    3. 3.3. ant 与 jsduck 结合
  4. 4. 参考文献

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太完美了以致于没有给你提供什么可以自己定制的余地。

我的选择

我个人比较喜欢JSDuck。下文主要说下JSDuck的使用。

步骤一:下载文件

首先在github 上下载最新版的二进制版本,下载之后只有一个exe文件,此文件中已捆绑好了ruby解释器,不需要另外独立安装。
路径:https://github.com/senchalabs/jsduck/releases

步骤二:执行命令

jsduck-6.0.0-beta.exe src --output docs  #成功创建docs 

说明:第一个src是要生成注释文档的目标文件夹,第二个–output docs是生成后文件夹保存的位置。

常用命令

 
–builtin-classes:构建javascript语言内建类文档,如Array或Object类的使用说明。 
–output:文档输出所在目录。 
–encoding:编码默认为utf-8,如果js文件中包含了中文字符设置gbk即可。 
–welcome:为一个html文件的路径,文件中的内容会被解析出来放到文档的欢迎页显示。 
–eg-iframe:配置一个html文件路径,这个html文件用来配置@example范例的预览方式,如需要生成非ExtJs或者sencha touch项目的话通常都需要自定义配置。 
–images:如果文档中引入了图片需配置一个图片目录。 
–title:自定义文档的标题 
–footer:自定义文档脚注 
–help:full 显示帮助文档。

注释语法

常用注解

@abstract
@accessor
@alias
@alternateClassName
@aside
@author 作者 
@cfg
@chainable
@class 类
@constructor
@deprecated 标记此方法属性或者类不赞成使用,在升级过渡的时候需兼容之前的API时特别有用。
@docauthor
@enum
@event 标记一个事件,随后通常会跟随@param标签给事件回调函数声明参数的说明。
@evented
@example 给类或者方法添加一个代码范例,jsduck不仅会给代码着色,还能给代码生成一个代码编辑器,编辑代码后可实时预览,使用@example需要四个空格的缩进。
@experimental
@extends 标记一个类继承自另一个类,生成后会有一个类型继承体系陈列在文档视图的右侧。 
@fires (in 5.x beta)
@ftype
@hide
@ignore
@inheritable
@inheritdoc
@localdoc (in 5.x beta)
@markdown
@member
@method
@mixins
@new
@override
@param    与@cfg类似,给一个函数成员标记其所需的参数类型和描述
@preventable
@private 将成员标记成私有,虽然也有@public但如果不特殊标明即为公有。 
@property 
@protected 将成员标记成受保护的。 
@ptype 
@readonly
@removed
@requires
@return 与@cfg类似,标记一个函数成员调用过后的返回类型。
@scss mixin
@since
@singleton
@static 将成员标记成静态的,静态成员也会在文档中进行分类展示。 
@template
@throws
@type
@uses
@var
@xtype

其他注解

{@link} 在文档注释中标记某个类或类成员的锚点。  
{@img} 在文档注释中链接一张图片,让文档变得更具可读性。
{@video}

ant 与 jsduck 结合

<property name="src" location="src"/>
<property name="docs" location="docs"/>
<property name="jsduck.path" location="tools/lib/jsduck-6.0.0-beta.exe"/>
<target name="document">
    <echo message="生成文档开始!!!"/>
    <apply executable="${jsduck.path}" failonerror="true" parallel="false">
        <fileset dir="${src}" includes="helper/*.js"/>
        <!-- 文档输出所在目录 -->
        <arg line="--output ${docs}"/>
        <!-- 编码默认为utf-8 -->
        <arg line="--encoding utf-8"/>
        <!-- 构建javascript语言内建类文档,如Array或Object类的使用说明 -->
        <arg line="--builtin-classes"/>
    </apply>
    <echo message="生成文档结束!!!"/>
</target>

参考文献

JSDuck官方指南: https://github.com/senchalabs/jsduck/wiki

(完)

微信公众号

文章目录

  1. 1. 为什么需要Javascript文档
  2. 2. 主流的Javascript注释文档生成工具
    1. 2.1. JSDoc 3
    2. 2.2. YUIDoc
    3. 2.3. Dox
    4. 2.4. Docco
    5. 2.5. JSDuck
  3. 3. 我的选择
    1. 3.1. 步骤一:下载文件
    2. 3.2. 步骤二:执行命令
      1. 3.2.1. 常用命令
      2. 3.2.2. 注释语法
    3. 3.3. ant 与 jsduck 结合
  4. 4. 参考文献