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

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

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

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

44
coffeescript google-closure-compiler javascript jsdoc

5 ответов

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

кроме того, в то время как компилятор закрытия имеет фирменное наименование Google за ним,UglifyJS доказывало быть более эффективным инструментом minification в много случаев. (на jQuery недавно перешли к нему.)

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

да:

### foo ###

или

`// foo`
4

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

75

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

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

компилятор 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; оператор над функцией будет создавать проблему. Если бы ты ... --7--> объявлено ранее, maybee..

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

6

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

0