javascript - sublime - ¿Cómo documentar el código fuente de CoffeeScript con JSDoc?

docblockr sublime

Question

Tengo un código escrito en CoffeeScript y quiero optimizar el JavaScript generado con el compilador de cierre de Google, por lo que estos archivos deben documentarse con JSDoc.

Mi pregunta es, ¿cómo puedo documentar los archivos * .coffee para generar javascript que contenga JSDoc de trabajo para el compilador de cierre?

Una pregunta más: ¿hay una manera de mantener un comentario de una sola línea en * .coffee?

Answer 1

Entrada de 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

Salida de JavaScript del indicador de Windows cmd para: 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;
};

Editar

Como se detalla en otra respuesta, CoffeeScript 1.7.1 tiene un mejor método disponible para resolver este problema.

Answer 2

Tendrás que experimentar (mucho), pero ### comentarios es tu amigo.

El compilador de coffee-script mantendrá los comentarios que utilizan el formulario ### (docs here ).

Intenté crear un fragmento JsDoc realmente simple para una función que usa la función ''try coffeescript'' en el sitio:

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

Esto dio:

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

No soy un experto en JsDoc , pero estoy adivinando la var foo; declaración sobre la función creará un problema. Si has declarado foo antes, Maybee ..

Sería bueno saber cómo va.

Answer 3

Ya que no puedo responder directamente a Billy arriba, parece que CoffeeScript 1.7.1 tiene mejor soporte para esto:

###*
# Sets the language and redraws the UI.
# @param {object} data Object with `language` property
# @param {string} data.language Language code
###

handleLanguageSet: (data) ->

salidas

/**
 * Sets the language and redraws the UI.
 * @param {object} data Object with `language` property
 * @param {string} data.language Language code
 */
handleLanguageSet: function(data) {}

Answer 4

Yo aconsejaría en contra de esto. JSDoconación de todo su código es un proceso laborioso que es probable que produzca poco o ningún beneficio con el compilador de cierre. Fuera de Google, casi nadie hace esto. CoffeeScripters / JavaScripters generalmente prefieren herramientas de documentación ligeras como docco .

Además, mientras que Closure Compiler tiene el nombre de la marca Google detrás, UglifyJS ha demostrado ser la herramienta de UglifyJS más eficiente en muchos casos. (jQuery recientemente cambió a él).

Una pregunta más: ¿hay una manera de mantener un comentario de una sola línea en * .coffee?

Sí:

### foo ###

o

`// foo`

Answer 5

class tiene un problema

###* this is a class ###
class hello
    v: 4

da eso

// Generated by CoffeeScript 2.0.0-beta5
/** this is a class */
var hello;

hello = (function() {
  class hello {};

  hello.prototype.v = 4;

  return hello;

})();

y no es válido en JSDoc