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

Question

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

我的问题是，如何记录*.coffee文件，以生成包含有效JSDoc的JavaScript文件，以供闭包编译器使用？

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

- aztack

---

请选一个回答来解决你的问题：如何为*.coffee文件编写文档以生成包含有效JSDoc的JavaScript，以供闭包编译器使用？ - Patrick McLaren

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命令提示符下输出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;
};

编辑

正如其他答案中详细说明的那样，CoffeeScript 1.7.1有更好的方法来解决这个问题。

- Billy Moon

---

请注意，CoffeeScript 编译器在注释后添加空格，因此某些解析器可能无法将其识别为 JSDoc。据我从其他文档工具的经验来看，这应该恰好是方法定义开始前一行。 - Len

这似乎不再起作用了。使用CoffeeScript 1.6.3，JavaScript输出在函数定义之前包含一个var cube，这会阻止JSDoc 3.2.0为该函数生成文档。 - rvernica

话虽如此，我并没有尝试过 JSDoc 3.2.0 - 所以实际上可能根本不起作用，因为我方法的意图是在块之前定义变量。 - Billy Moon

"对你所有的代码进行JSDoc注释是一项繁琐的过程，很可能无法从闭包编译器中获得任何好处。" 上述引用。我非常赞同。而伪JSDoc注释CoffeeScript代码，希望最终输出符合有效的JSDoc格式几乎毫无益处。它可能在某些版本上运行良好。但是，“可能”并不值得这样做的努力。" - Lukas Bünger

@BillyMoon，我无法在CoffeeScript中使用类方法使其正常工作。 - boh

Answer 2

由于我无法直接回复上面的Billy，据看来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) {}

- mike wyatt

---

请注意，这并不能解决您必须先声明变量的问题（Billy答案的第一行）。 - phil294

Answer 3

您需要进行试验（很多次），但###注释是您的朋友。

使用###形式的注释，咖啡编译器将保留这些注释（文档 在此）。

我尝试使用该网站的“尝试咖啡脚本”功能来创建一个非常简单的JsDoc片段用于函数：

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

这给出了：

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

我不是JsDoc专家，但我猜测函数上面的var foo;语句会创建问题。如果之前已经声明了foo，那么可能就不会出现这样的问题。
很想听听它的进展如何。

- Jacob Oscarson

Answer 4

我建议不要这样做。对你的所有代码进行 JSDoc 处理是一项繁琐的过程，很可能不会从 Closure Compiler 中获得任何好处。除了 Google 本身外，几乎没有人这样做。CoffeeScripters/JavaScripters 通常更喜欢像 docco 这样的轻量级文档工具。

此外，虽然 Closure Compiler 背后有 Google 品牌，但在许多情况下，UglifyJS 已被证明是更有效的缩小工具。（jQuery 最近转向 使用它。）

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

是的：

### foo ###

或者

`// foo`

- Trevor Burnham

---

“// foo” 会在行末添加一个“;”，有没有办法将其删除？ - aztack

当在高级模式下使用时，Google Closure编译器提供了无与伦比的压缩和执行速度。请参见http://jsperf.com/testing-code-performance-by-compression-type上的基准测试。 - Aleš Kotnik

JSDoc有许多优点，不仅仅局限于Closure编译器的优化，它可以制作出看起来很好的编译文档，而且更重要的是，如果你使用JSDoc，一款良好的IDE可以进行代码和类型提示、提供警告/错误，并使@see/@link变得可导航。考虑到无数Bug的根源要么是缺乏签名，要么是缺乏对签名的遵守，我认为在任何JS中，不管是否被压缩，JSDoc都非常重要（有一些IDE如PHPStorm也可以在CoffeeScript环境下愉快地处理它）。 - Ezekiel Victor

不想太反驳，但是您所说的docco怎么可能是“轻量级文档”呢？它需要第三方组件、额外配置、在您的构建例程中添加另一个编译例程，最糟糕的是开发者需要额外花时间来创建漂亮的冗长注释，这些注释在原始源代码的上下文中并不具有功能性（请参阅上面的JSDoc参数）。 - Ezekiel Victor

这个“回答”忽略了问题，而是表达了个人观点。 - rath

-1 这完全没有回答问题。首先，您似乎完全忽略了jsDoc的重点。其次，docco作为“轻量级文档工具”是牵强附会的。 - losnir

Answer 5

类有问题

###* 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 中是无效的

- Li Hanyuan