如何使用JSDoc文档CoffeeScript源代码

How to document CoffeeScript source code with JSDoc?

本文关键字：CoffeeScript 源代码 文档 JSDoc 何使用      更新时间：2023-09-26

我有一些用CoffeeScript编写的代码，我想用谷歌闭包编译器优化生成的JavaScript，所以这些文件需要用JSDoc进行记录。

我的问题是，如何对*.coffee文件进行文档化，为闭包编译器生成包含工作JSDoc的javascript？

还有一个问题：有没有办法在*.coffee中保留一行评论？

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从windows cmd提示符输出：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，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) {}

您必须进行大量实验，但###注释是您的朋友。

coffee脚本编译器将保留使用###表单的注释(此处为文档(。

我尝试使用网站上的"尝试咖啡脚本"功能为一个函数创建一个非常简单的JsDoc片段：

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

这给出了：

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

我不是JsDoc的专家，但我猜函数上面的var foo;语句会产生问题。如果您之前已声明foo，则maybee。。

如果能听听进展如何，那就太好了。

我建议不要这样做。JSDoc编写所有代码是一个费力的过程，很可能不会从闭包编译器中获得什么好处。除了谷歌本身，几乎没有人这样做。CoffeeScripters/JavaScripters通常更喜欢像docco这样的轻量级文档工具。

此外，尽管Closure Compiler背后有谷歌的品牌名称，但在许多情况下，UglifyJS已被证明是更有效的缩小工具。(jQuery最近切换到了它。(

还有一个问题：有没有办法在*.coffee中保留一行评论？

是：

### foo ###

或

`// foo`

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 中无效

相关文章：