简介
在前端开发中，文档和注释是一个重要环节。能够清晰地描述代码作用和用法，能够快速解决问题。JS 的文档工具很多，比如 JSDoc、YUIDoc 等等。而 CoffeeScript 的文档工具选择就比较少了，当前比较好用的是 coffeejsdoc。
coffeejsdoc 是一个基于 JSDoc 的 CoffeeScript 文档工具，可以生成 HTML 文档或 Markdown 文档。本文将介绍如何使用这个工具为 CoffeeScript 代码生成文档，以及如何在文档中使用 Markdown。
安装 coffeejsdoc
使用 npm 安装 coffeejsdoc：
--- ------- -- ------------
安装完成后，可以通过以下命令检查是否安装成功：
----------- --
如果能够正确输出版本号，就说明 coffeejsdoc 安装成功了。
编写文档注释
使用 coffeejsdoc 生成文档，需要在 CoffeeScript 代码中加入文档注释。注释必须以 /** 开头，以 */ 结尾。中间每一行都以 * 开头。如下所示：
---
- ------ -------
-
- ---- -- - ----- -----------
-
- ------ -------- ---- - --- ---- -- --- ----
- ------ -------- --- - --- --- -- --- ----
- ------- ------ --- ------- ---- ------
-
----- -------
------------ ------ ---- --
----- - ----
---- - ---上面的例子中，注释部分已经包含了类名、类描述以及构造函数的参数、返回值等信息。
下面是常用的注释标签说明：
- @class/classdesc：类或模块描述
- @param：函数参数描述
- @return：函数返回值描述
- @property：对象属性描述
- @example：示例代码
生成文档
使用 coffeejsdoc 生成文档非常简单，只需要使用以下命令即可：
----------- -------------- -- ---- -------- -----------
其中：
myclass.coffee是要生成文档的 CoffeeScript 文件-o指定生成的文档输出目录--config指定配置文件
下面是一个样例配置文件：
-
------- -
------------------- ----
--
---------- -
------------------
--
------- -
-------------- ---------
---------- -----
---------- -----
---------- -----
----------- ----------------------------------------
-------- --------
-
-配置文件说明：
tags.allowUnknownTags：是否允许未知标签plugins：指定使用的插件，这里指定使用 markdown 插件opts.destination：指定生成文档的输出目录opts.recurse：是否递归生成子目录中的文档opts.private：是否生成私有成员的文档opts.lenient：是否宽松模式（即忽略错误）opts.template：指定使用的模版目录opts.theme：指定使用的主题样式（可选）
使用 Markdown
在注释中使用 Markdown 很简单，只需要在注释内容中使用 Markdown 语法即可。例如：
--- - ------- ------- - - ---- -- - ------ ------------ - ---- -- -- -------- - - --- ------ - ----- - ------- ------ - ------ - -------------------------- - ----------- ------ - --- - - ------ -------- ----- - --- ----- ------ - ------- -------- --- --------- ------ - -------- ------- -- - --------------
注释中使用三个反引号包含起来的代码块会自动语法高亮。效果如下：
---- -- - ------ ------------ ---- -- -- -------- --- ------ ----- - ------- ------ ------ - -------------------------- ----------- ------
-- --- --------------- ----------- - ------------ ----------------- -------- -------------------------------------------- ----------------------------------------------------------- ---------- ---------------------------------------------------------------------------------------