在前端开发过程中，我们经常需要对代码进行注释和文档化，以便于团队协作和维护。此时，JSDoc 是一个非常好用的工具，它可以帮助我们自动生成 API 文档，并且支持多种编程语言。而如果你使用 CoffeeScript 编写代码，则需要一些额外的配置才能让 JSDoc 正确地解析你的源代码文件。
安装 JSDoc
首先，我们需要安装 JSDoc。可以使用 npm 来进行安装：
npm install -g jsdoc
配置 JSDoc 支持 CoffeeScript
默认情况下，JSDoc 并不支持 CoffeeScript，因此我们需要一些额外的配置来使其正常工作。
安装 jsdoc-coffee-plugin
首先，我们需要安装一个名为 jsdoc-coffee-plugin 的插件，这个插件可以让 JSDoc 支持 CoffeeScript。可以使用 npm 进行安装：
npm install --save-dev jsdoc-coffee-plugin
修改配置文件
接下来，我们需要修改 JSDoc 的配置文件 jsdoc.conf.json，添加以下内容：
-- -------------------- ---- -------
-
---------- -
-------------------
----------------------------------
--
--------- -
----------------- ---------------
----------------- ---------------
--
------- -
----------- -------------------------------------
-------------- ----------
---------- ----
-
-在这个配置文件中，我们通过 plugins 属性添加了两个插件：markdown 和 jsdoc-coffee-plugin。同时，我们还修改了 source 属性，使其能够正确地解析 CoffeeScript 文件。
添加 JSDoc 注释
最后，我们需要在代码文件中添加 JSDoc 注释。以下是一个简单的示例：
# Get the sum of two numbers.
#
# @param {number} a - The first number to add.
# @param {number} b - The second number to add.
# @returns {number} The sum of a and b.
getSum = (a, b) ->
return a + b在这个示例中，我们使用 JSDoc 注释来描述函数的参数和返回值。其中，@param 用于描述参数，@returns 用于描述返回值。
生成 API 文档
完成上述步骤后，我们就可以使用 JSDoc 来自动生成 API 文档了。在命令行中执行以下命令即可：
jsdoc path/to/source/files.coffee
执行完毕后，JSDoc 将会在 ./docs/ 目录下生成 API 文档。
总结
本文介绍了如何使用 JSDoc 和 CoffeeScript 进行代码注释和文档化。具体而言，我们需要安装 JSDoc、安装 jsdoc-coffee-plugin、修改配置文件和添加 JSDoc 注释。通过这些步骤，我们可以方便地生成 API 文档，提高代码的可维护性和可读性。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/15676