javascript 如何使用 JSDoc 记录 CoffeeScript 源代码？
声明：本页面是StackOverFlow热门问题的中英对照翻译，遵循CC BY-SA 4.0协议，如果您需要使用它，必须同样遵循CC BY-SA许可，注明原文地址和作者信息，同时你必须将它归于原作者（不是我）：StackOverFlow
原文地址: http://stackoverflow.com/questions/7833021/
Warning: these are provided under cc-by-sa 4.0 license. You are free to use/share it, But you must attribute it to the original authors (not me):
StackOverFlow
How to document CoffeeScript source code with JSDoc?
提问by aztack
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 中保留单行注释？
采纳答案by Trevor Burnham
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.
我建议不要这样做。对所有代码进行 JSDoc-ing 是一个费力的过程，很可能不会从 Closure Compiler 中产生什么好处。除了谷歌本身，几乎没有人这样做。CoffeeScripters/JavaScripters 通常更喜欢像docco这样的轻量级文档工具。
Also, while Closure Compiler has the Google brand name behind it, UglifyJShas proven to be the more efficient minification tool in many cases. (jQuery recently switchedto 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`
回答by Billy Moon
CoffeeScript Input:
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
JavaScript Output from windows cmd prompt for: coffee -cpb src.coffee
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;
};
Edit
编辑
As detailed in other answerCoffeeScript 1.7.1 has better method available to solve this problem.
正如其他答案中所述，CoffeeScript 1.7.1 有更好的方法来解决这个问题。
回答by mike wyatt
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) {}
回答by Jacob Oscarson
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).
咖啡脚本编译器将保留使用###表单的注释（此处为文档）。
I tried to create a really simple JsDocfragment for a function using the 'try coffeescript' feature at the site:
我尝试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 foodeclared before, maybee..
我不是 专家JsDoc，但我猜var foo;函数上面的语句会产生问题。如果你之前foo声明过，也许...
It'd be nice to heare how it goes.
很高兴听到进展如何。
回答by Li Hanyuan
classhas a problem
class有问题
###* 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 中无效
