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

I have some code written in CoffeeScript and I want to optimize the generated JavaScript with the Google Closure Compiler, so these files need to be documented with JSDoc.

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

My question is, how can I document the *.coffee files to generate javascript containing working JSDoc for the closure compiler?

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

One more question: is there a way to keep a single-line comment in *.coffee ?

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

5 个解决方案

#1

I'd advise against this. JSDoc-ing all of your code is a laborious process that's likely to yield little to no benefit from the Closure Compiler. Outside of Google itself, hardly anyone does this. CoffeeScripters/JavaScripters generally prefer lightweight documentation tools like docco.

我建议不要这样做。 JSDocing您的所有代码是一个费力的过程，可能从Closure Compiler几乎没有任何好处。在Google本身之外，几乎没有人这样做。 CoffeeScripters / JavaScripters通常更喜欢像docco这样的轻量级文档工具。

Also, while Closure Compiler has the Google brand name behind it, UglifyJS has proven to be the more efficient minification tool in many cases. (jQuery recently switched to it.)

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

One more question: is there a way to keep a single-line comment in *.coffee ?

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

Yes:

是：

### foo ###

or

要么

`// foo`

#2

CoffeeScript Input:

### 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

JavaScript Output from windows cmd prompt for: 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;
};

Edit

As detailed in other answer CoffeeScript 1.7.1 has better method available to solve this problem.

正如其他答案中详述的那样，CoffeeScript 1.7.1有更好的方法可以解决这个问题。

#3

Since I cannot respond directly to Billy above, it seems CoffeeScript 1.7.1 has better support for this:

由于我无法直接回复上面的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) ->

outputs

输出

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

#4

You'll have to experiment (a lot), but ### comments is your friend.

你必须进行实验（很多），但###评论是你的朋友。

The coffee-script compiler will keep comments that use the ### form (docs here).

咖啡脚本编译器将保留使用###表单的注释（此处为docs）。

I tried to create a really simple JsDoc fragment for a function using the 'try coffeescript' feature at the site:

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

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

This gave:

这给了：

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

I'm no expert in JsDoc, but I'm guessing the var foo; statement above the function will create a problem. If you had foo declared before, maybee..

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

It'd be nice to heare how it goes.

听听它是怎么回事真好。

#5

class has a problem

上课有问题

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

gives that

给出了

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

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

  hello.prototype.v = 4;

  return hello;

})();

and it's invalid in JSDoc

它在JSDoc中无效