python画风景图_风景侠

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

优点

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

安装 ruby

从 github 上下载并解压 JSduck，解压目录中 JSdcuck.exe 既是可运行文件

将 JSduck 的运行目录配置到 PATH 当中

运行 JSduck

从 cmd 中输入以下命令即可运行

jsduck —output

JSduck API

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

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

@author 指定类/方法的作者

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

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

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

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

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

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

@event 描述一个事件的定义

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

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

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

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

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

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

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

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

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

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

@scss mixin

@since 描述从哪个版本开始加入的新的对象，使用该标记

时，会在文档中自动加入 @new 标记，但不会影响源代码。

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

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

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

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

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