Comment documenter le code source CoffeeScript avec JSDoc ?

Question

J'ai du code écrit en CoffeeScript et je veux optimiser le JavaScript généré avec le Google Closure Compiler, donc ces fichiers doivent être documentés avec JSDoc.

Ma question est la suivante : comment puis-je documenter les fichiers *.coffee pour générer du javascript contenant du JSDoc fonctionnel pour le compilateur de fermeture ?

Une autre question : existe-t-il un moyen de conserver un commentaire d'une seule ligne dans *.coffee ?

Answer 1

Entrée 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

Sortie JavaScript de l'invite cmd de Windows pour : 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;
};

Modifier

Comme détaillé dans autre réponse CoffeeScript 1.7.1 dispose d'une meilleure méthode pour résoudre ce problème.

Answer 2

Comme je ne peux pas répondre directement à Billy ci-dessus, il semble que CoffeeScript 1.7.1 ait un meilleur support pour cela :

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

handleLanguageSet: (data) ->

sorties

/**
 * 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

Vous devrez expérimenter (beaucoup), mais ### Les commentaires sont votre ami.

Le compilateur coffee-script conservera les commentaires qui utilisent l'attribut ### formulaire (docs aquí ).

J'ai essayé de créer un système très simple JsDoc pour une fonction utilisant la fonction "try coffeescript" sur le site :

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

Cela a donné :

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

Je ne suis pas un expert en JsDoc mais je suppose que le var foo; au-dessus de la fonction va créer un problème. Si vous aviez foo déclaré avant, peut-être

Ce serait bien d'entendre comment ça se passe.

Answer 4

Je vous le déconseille. JSDoc-er l'ensemble de votre code est un processus laborieux qui est susceptible de produire peu ou pas de bénéfice du Closure Compiler. En dehors de Google lui-même, presque personne ne le fait. Les CoffeeScripters/JavaScripters préfèrent généralement des outils de documentation légers tels que docco .

Aussi, alors que Closure Compiler a la marque Google derrière lui, UglifyJS s'est avéré être l'outil de minification le plus efficace dans de nombreux cas. (jQuery récemment changé à elle.)

Une autre question : existe-t-il un moyen de conserver un commentaire d'une seule ligne dans *.coffee ?

Oui :

### foo ###

o

`// foo`

Answer 5

class a un problème

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

donne que

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

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

  hello.prototype.v = 4;

  return hello;

})();

et c'est invalide dans JSDoc