如何使用 JSDoc 记录 CoffeeScript 源代码？

Question

我有一些用 CoffeeScript 编写的代码，我想用 Google Closure Compiler 优化生成的 JavaScript，所以这些文件需要用 JSDoc 记录。

我的问题是，如何记录 *.coffee 文件以生成包含用于闭包编译器的工作 JSDoc 的 javascript？

还有一个问题：有没有办法在 *.coffee 中保留单行注释？

Answer 1

CoffeeScript 输入：

### define function variable before block to avoid code being appended to closing part of JSDoc comment ###
cube = null

###*
 * Function to calculate cube of input
 * @param {number} Number to operate on
 * @return {number} Cube of input
 ###

cube = (x) -> x*x*x

Windows cmd 提示符的 JavaScript 输出：coffee -cpb src.coffee

// Generated by CoffeeScript 1.6.3
/* define function variable before block to avoid code being appended to closing part of JSDoc comment*/

var cube;

cube = null;

/**
 * Function to calculate cube of input
 * @param {number} Number to operate on
 * @return {number} Cube of input
*/

cube = function(x) {
  return x * x * x;
};

编辑

正如other answerCoffeeScript 1.7.1 中详细介绍的那样，有更好的方法可以解决这个问题。

Answer 2

由于我无法直接回复上面的比利，看来 CoffeeScript 1.7.1 对此有更好的支持：

###*
# Sets the language and redraws the UI.
# @param {object} data Object with `language` property
# @param {string} data.language Language code
###

handleLanguageSet: (data) ->

输出

/**
 * Sets the language and redraws the UI.
 * @param {object} data Object with `language` property
 * @param {string} data.language Language code
 */
handleLanguageSet: function(data) {}

Answer 3

你必须尝试（很多），但### cmets 是你的朋友。

coffee-script 编译器将保留使用 ### 形式的 cmets（文档 here）。

我尝试使用站点上的“try coffeescript”功能为函数创建一个非常简单的 JsDoc 片段：

###* Doc for this function.###
foo = -> 'bar'

这给了：

/** Doc for this function.
*/
var foo;
foo = function() {
   return 'bar';
 };

我不是JsDoc 方面的专家，但我猜测函数上方的var foo; 语句会产生问题。如果你之前声明过foo，也许……

很高兴知道进展如何。

Answer 4

我建议不要这样做。对所有代码进行 JSDoc 处理是一个费力的过程，很可能从 Closure Compiler 中几乎没有收益。在谷歌本身之外，几乎没有人这样做。 CoffeeScripters/JavaScripters 通常更喜欢 docco 这样的轻量级文档工具。

此外，虽然 Closure Compiler 背后有 Google 品牌名称，但 UglifyJS 在许多情况下已被证明是更有效的缩小工具。 （jQuery recently switched 给它。）

还有一个问题：有没有办法在 *.coffee 中保留单行注释？

是的：

### foo ###

或

`// foo`

Answer 5

class有问题

###* this is a class ###
class hello
    v: 4

给出了

// Generated by CoffeeScript 2.0.0-beta5
/** this is a class */
var hello;

hello = (function() {
  class hello {};

  hello.prototype.v = 4;

  return hello;

})();

在 JSDoc 中无效