使用JSduck生成技术文档

## 为什么要有技术文档?

优点
1. 如果代码看不下去,那么看文档
2. 对功能模块有一个全局的视角
3. 使项目易于维护

缺点
1. 需要额外的人力来整理文档
2. 需要额外的时间来做文档的变更

so,有没有一种更简单的方式,在现有人力的情况下,在限有时间的前提下,做到技术文档的输出呢?

其实,可以用框架来生成技术文档,这个框架就是 JSduck

JSduck由Sencha开发,因此对于自家extJS具有非常强大的支持功能,包括令人咋舌的实时代码修改。但即使你不是使用extJS进行开发,JSDuck仍然是一个非常强大的工具,一方面它的语法非常灵活,描述支持Markdown语法,上手难度远远低于JSDoc

3;另一方面它生成的文档可读性堪比YUIDoc,同时支持源码的对照,学习起来也非常的容易。要说JSduck有什么不好的地方,估计就是它把一切都Handle太完美了以致于没有给你提供什么可以自己定制的余地。

JSduck 运行原理?

JSduck + 代码注释=文档 JSduck 也是一套程序库,运行这个程序库,它会读取你的源代码中的注释文档,最终生成一套网页文件,这些文件既是文档。

      • 注释规范需以“/*” 开头和“/”结束,不同的注释标签会生成不同的文档内容,JSduck提供了很多注释标签,大部分都是通用的注释标签,例如 @auther 用来指定代码作者,@return 用来描述方法的返回值,@param 用来描述输入参数等等。

        安装 JSduck

  1. 安装 ruby
  2. 从 github 上下载并解压 JSduck,解压目录中 JSdcuck.exe 既是可运行文件
  3. 将 JSduck 的运行目录配置到 PATH 当中

运行 JSduck

从 cmd 中输入以下命令即可运行
jsduck <源代码目录> —output <文档输出目录>

JSduck API

JSduck 玩的就是注释符,下面是 JSduck 提供的所有注释符

@abstract用来标记抽象方法或类,通常用于标记还有没实现的方法

@accessor

@alias

@alternateClassName

@aside

@author 指定类/方法的作者

@cfg 用于组件或类的配置描述

@chainable 用于标记一组链路方法,链路方法是什么?我的理解是方法总会返回 this

@class** 标记一个类,JSduck 会根据该标记来生成树的结构图

@constructor 如果为了一个类写了构造函数,那么需要使用改注释符

@deprecated 如果某一个函数不再使用,但是为了不影响线上版本不能删除改方法的情况下,需要将改函数标记为已废弃

@docauthor 类似于 @author,不过 @author 用于代码的作者,该标记用于描述文档的编写者

@enum 枚举

@event 描述一个事件的定义

@evented 描述一个事件的影响者

@experimental 用于描述一个不稳定的方法,因为改方法可能会在以后的版本中移除掉,以此来警告方法的使用者

@extends 继承

@fires 描述某一个方法中,可能会触发某一个事件

@ftype

@hide

@ignore 某些注释只用于开发者阅读,但是并不希望在出现在文档中,可以使用该标记

@inheritable

@inheritdoc

@link 用于引用其他对象(类,方法,事件等)

@localdoc

@markdown

@member

@method 描述一个方法

@mixins 混合某一个对象的注释

@new 标记某一个最新创建的方法

@override

@param 描述入参

@preventable

@private 描述私有对象

@property描述属性

@protected将成员的可见性记录为受保护。受保护的成员只能从类本身及其子类中使用。

@ptype

@readonly描述只读属性

@removed 描述某一个方法在某一个版本中已经移除掉

@requires描述依赖对象

@return** 描述方法的返回对象

@scss mixin
@since 描述从哪个版本开始加入的新的对象,使用该标记
时,会在文档中自动加入 @new 标记,但不会影响源代码。

@singleton描述单态对象

@static描述静态对象

@template提供一种作为扩展类的功能的钩子提供的方法。该标签通常与@protected一起使用。

@throws 文件方法抛出的异常。异常类型默认为Object。可以使用多个@throws标签来记录多个可能的异常。

@type** 记录属性的类型,另外将记录的东西标记为属性。 不建议使用此标记。它只支持向后兼容旧的ext-doc。对于新代码,始终使用@property标签。

@uses** 定义文档类使用的类。

@var** 记录SCSS变量:其名称,类型和默认值。

@xtype