web-dev-qa-db-fra.com

Comment documenter le code source CoffeeScript avec JSDoc?

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, comment puis-je documenter les fichiers * .coffee pour générer du javascript contenant JSDoc de travail pour le compilateur de fermeture?

Une dernière question: existe-t-il un moyen de conserver un commentaire sur une seule ligne dans * .coffee?

javascriptcoffeescriptgoogle-closure-compilerjsdoc
45
aztack

Je déconseille cela. JSDoc-ing tout votre code est un processus laborieux qui est susceptible de produire peu ou pas d'avantages du compilateur de fermeture. En dehors de Google lui-même, presque personne ne le fait. CoffeeScripters/JavaScripters préfèrent généralement des outils de documentation légers comme docco .

En outre, alors que Closure Compiler a le nom de marque Google derrière lui, glifyJS s'est avéré être l'outil de minification le plus efficace dans de nombreux cas. (jQuery récemment changé vers lui.)

Une dernière question: existe-t-il un moyen de conserver un commentaire sur une seule ligne dans * .coffee?

Oui:

### foo ###

ou

`// foo`
3
Trevor Burnham

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 à partir de Windows cmd Demander: 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;
};

Éditer

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

78
Billy Moon

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) ->

les sorties

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

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

Le compilateur de script de café conservera les commentaires qui utilisent le ### formulaire (docs ici ).

J'ai essayé de créer un fragment JsDoc très simple pour une fonction en utilisant la fonctionnalité '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; L'instruction au-dessus de la fonction créera un problème. Si vous aviez foo déclaré auparavant, maybee ..

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

6
Jacob Oscarson

class a un problème

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

donne ça

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

0
Li Hanyuan