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

Question

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

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

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

Answer 1

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

Answer 2

Поскольку я не могу ответить непосредственно на Билли выше, кажется, что 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) {}

Answer 3

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

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

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

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

Это дало:

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

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

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

Answer 4

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

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

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

Да

### foo ###

или

`// foo`

Answer 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