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

Posted 2023-03-03

【中文标题】如何使用 JSDoc 记录 CoffeeScript 源代码？

【英文标题】：How to document CoffeeScript source code with JSDoc?

【发布时间】：2011-12-11 14:13:35

【问题描述】：

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

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

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

【问题讨论】：

请选择一个能解决您的问题的答案：如何记录 *.coffee 文件以生成包含用于闭包编译器的工作 JSDoc 的 javascript？

【参考方案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 中详细介绍的那样，有更好的方法可以解决这个问题。

【讨论】：

注意：Coffeescript 编译器在注释后添加了空格，因此，一些解析器可能不会将其识别为 JSDoc，我认为（根据其他文档工具的经验），应该正好是方法定义开始

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

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

“JSDoc-ing 你所有的代码是一个费力的过程，很可能从闭包编译器中产生很少甚至没有任何好处”上面的引用。我完全同意。而伪 JSDoc-ing CoffeeScript 代码，希望得到的输出最终符合有效的 JSDoc 格式，几乎没有任何好处。可以在某些版本中正常工作。但是“可能”是不值得的。

@BillyMoon 我无法让它与 CoffeeScript 中的类方法一起使用。

【参考方案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) 

【讨论】：

请注意，这并不能解决您必须事先声明变量的问题（比利回答的第一行）

【参考方案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，也许……

很高兴知道进展如何。

【参考方案4】：

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

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

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

是的：

### foo ###

或

`// foo`

【讨论】：

// foo 将添加一个“;”在行尾，有没有办法删除它？

在高级模式下使用时，谷歌闭包编译器提供了无与伦比的压缩和执行速度。请参阅jsperf.com/testing-code-performance-by-compression-type

的基准测试

JSDoc 有许多超越 Closure Compiler 优化的好处，可以说比制作漂亮的编译文档更重要。如果你使用 JSDoc，一个好的 IDE 可以编码和输入提示，给出警告/错误，并使@see/@link 可导航。考虑到无数错误的根源是缺乏签名或缺乏对它的遵守，我认为 JSDoc 在任何 JS 中都很重要，无论是否缩小（并且有一些 IDE，如 phpStorm 也很乐意在 CoffeeScript 上下文中消化它） .

另外，不要太逆势而上，但正如您所说，docco 是怎样的“轻量级文档”？它需要第三方组件、额外配置、另一个编译例程添加到您的构建例程中，最糟糕的是，开发人员需要额外注意才能生成在原始源代码上下文中不起作用的漂亮、臃肿的 cmets（请参阅 JSDoc以上论点）。

这个“答案”忽略了问题，支持个人观点。

【参考方案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 中无效