47

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 ?

Brad Koch
  • 19,267
  • 19
  • 110
  • 137
aztack
  • 4,376
  • 5
  • 32
  • 50
  • 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?_ – Patrick McLaren Nov 16 '17 at 20:18

5 Answers5

79

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.

Community
  • 1
  • 1
Billy Moon
  • 57,113
  • 24
  • 136
  • 237
  • 4
    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 – Len Feb 26 '13 at 16:45
  • 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. – rvernica Jul 16 '13 at 22:46
  • 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. – Billy Moon Jul 16 '13 at 23:00
  • "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. – Lukas Bünger Nov 28 '13 at 22:25
  • @BillyMoon I cant get it to work with class methods in CoffeeScript. – boh Sep 17 '14 at 07:24
36

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) {}
mike wyatt
  • 1,280
  • 11
  • 13
  • note that this does not solve the issue of you having to declare the variable beforehand (first line of Billy's answer) – phil294 Aug 08 '21 at 20:08
6

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.

Jacob Oscarson
  • 6,363
  • 1
  • 36
  • 46
2

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`
famousgarkin
  • 13,687
  • 5
  • 58
  • 74
Trevor Burnham
  • 76,828
  • 33
  • 160
  • 196
  • `// foo` will add a ";" at the end of line, is there a way to remove it? – aztack Oct 24 '11 at 03:29
  • 2
    When used in advanced mode, google closure compiler provides unmatched compression and execution speed. See benchmarks at http://jsperf.com/testing-code-performance-by-compression-type – Aleš Kotnik Feb 17 '13 at 00:53
  • 18
    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 Apr 30 '13 at 09:10
  • 4
    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). – Ezekiel Victor Apr 30 '13 at 09:14
  • 13
    This 'answer' ignores the question in favor of a personal opinion. – rath Mar 15 '14 at 02:07
  • -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. – losnir Feb 14 '16 at 16:08
0

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's invalid in JSDoc

Li Hanyuan
  • 506
  • 1
  • 4
  • 7