How to document CoffeeScript source code with JSDoc?

Question

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.

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

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

Solution 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.

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.)

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

Yes:

### foo ###

or

`// foo`

Solution 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.

Solution 3

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

###*
# 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) {}

Solution 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).

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

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

It'd be nice to heare how it goes.

View more solutions

Comments

[Patrick McLaren]

Please choose an answer that addresses your question: how can I document the *.coffee files to generate javascript containing working JSDoc for the closure compiler?

[aztack]

// foo will add a ";" at the end of line, is there a way to remove it?

[Aleš Kotnik]

When used in advanced mode, google closure compiler provides unmatched compression and execution speed. See benchmarks at jsperf.com/testing-code-performance-by-compression-type

[Len]

note: Coffeescript compiler adds whitespaces after comment, therefore, some parsers might not recognize it as JSDoc, which is, I think (from experience with other doc tooling), supposed to be exactly the line before the method definition starts

[Ezekiel Victor]

There are many benefits to JSDoc that go beyond Closure Compiler optimization, arguably more important than making great looking compiled documentation. If you use JSDoc, a good IDE can code and type hint, give warnings/errors, and make @see/@link navigable. Considering the root of countless bugs is either lack of signature or lack of adherence thereto, I would argue that JSDoc is important in any JS, minified or not (and there are some IDEs such as PHPStorm which happily digest it in CoffeeScript context as well).

[Ezekiel Victor]

Also, not to be too contrarian, but how is docco at all "lightweight documentation" as you say? It requires third party components, additional configuration, another compilation routine added to your build routine, and worst of all extra attention by the developer to produce nice, big bloated comments that aren't functional within the context of the original source code (see JSDoc arguments above).

[rvernica]

This does not seem to work any more. With CoffeeScript 1.6.3 the JavaScript output contains a var cube before the function definition which inhibits JSDoc 3.2.0 to generate documentation for the function.

[Billy Moon]

Having said that, I have not tried JSDoc 3.2.0 - so that might not work at all actually, as the intention of my method is to define the variable before the block.

[Lukas Bünger]

"JSDoc-ing all of your code is a laborious process that's likely to yield little to no benefit from the Closure Compiler" Quote from above. I couldn't agree more. And Pseudo-JSDoc-ing CoffeeScript code, hoping that the resulting output will eventually fit a valid JSDoc format yields close to no benefit at all. May work fine with some release. But "may" is just not worth the effort.

[rath]

This 'answer' ignores the question in favor of a personal opinion.

[boh]

@BillyMoon I cant get it to work with class methods in CoffeeScript.

[losnir]

-1 This does not answer the question at all. First of all, you seem to completely miss the point of jsDoc. Secondly, docco being a "lightweight documentation tool" is far fetched.

[phil294]

note that this does not solve the issue of you having to declare the variable beforehand (first line of Billy's answer)