Как документировать исходный код CoffeeScript с помощью JSDoc?

У меня есть код, написанный на CoffeeScript, и я хочу оптимизировать сгенерированный JavaScript с помощью Google Closure Compiler, поэтому эти файлы должны быть документированы с помощью JSDoc.

Мой вопрос в том, как я могу документировать файлы *. coffee для создания javascript, содержащего рабочий JSDoc для компилятора закрытия?

Еще один вопрос: есть ли способ сохранить однострочный комментарий в *. coffee?

Ответ 1

Я бы советовал против этого. JSDoc-ing весь ваш код - трудоемкий процесс, который вряд ли принесет пользу от компилятора Closure. Вне самой Google, вряд ли кто-то это делает. CoffeeScripters/JavaScript обычно предпочитают легкие инструменты для документации, такие как docco.

Кроме того, в то время как Closure Compiler имеет за собой фирменное наименование Google, UglifyJS оказался более эффективным инструментом для минимизации во многих случаях, (jQuery недавно переключился на него.)

Еще один вопрос: есть ли способ сохранить однострочный комментарий в *. coffee?

Да:

### foo ###

или

`// foo`

Ответ 2

Вход 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 из окна 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 есть лучший метод для решения этой проблемы.

Ответ 3

Поскольку я не могу напрямую ответить на 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) {}

Ответ 4

Вам придется экспериментировать (много), но ### комментарии - ваш друг.

Компилятор coffee- script будет хранить комментарии, которые используют форму ### (docs здесь).

Я попытался создать действительно простой фрагмент JsDoc для функции, используя функцию "try coffeescript" на сайте:

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

Это дало:

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

Я не эксперт в JsDoc, но я предполагаю, что оператор var foo; выше функции вызовет проблему. Если раньше у вас был foo, maybee..

Было бы здорово узнать, как это происходит.

Ответ 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