How to document CoffeeScript source code using JSDoc?

Question

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

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

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

Answer 1

I would advise against this. JSDoc-ing all your code is a laborious process that is unlikely to benefit from the Closure compiler. Outside of Google itself, hardly anyone does. CoffeeScripters / JavaScript usually prefers lightweight documentation tools such as docco .

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

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

Yes:

### foo ### 

or

 `// foo` 

Answer 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 cmd window 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 another answer . CoffeeScript 1.7.1 has a better method to solve this problem.

Answer 3

Since I cannot directly answer Billy above, CoffeeScript 1.7.1 seems to better support this:

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

exits

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

Answer 4

You will have to experiment (a lot), but ### comments are your friend.

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

I tried to create a really simple JsDoc fragment for a function using the "try coffeescript" function on the site:

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

It gave:

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

I am not an expert in JsDoc , but I assume the var foo; operator var foo; The above function will cause the problem. If you had foo before, maybee ..

It would be great to know how this happens.

Answer 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 is not valid in JSDoc