javascript - sublime - ¿Cómo documentar el código fuente de CoffeeScript con JSDoc?
docblockr sublime (5)
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?
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.
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.
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) {}
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`
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