Comment document CoffeeScript code source avec JSDoc?

J'ai un code écrit en CoffeeScript et je veux optimiser le JavaScript généré avec le Google Closure compiler, de sorte que ces fichiers doivent être documentées avec JSDoc.

Ma question est, comment puis-je le document *.le café des fichiers à générer le javascript contenant de travail JSDoc pour le compilateur de fermeture?

Encore une question: est-il un moyen de conserver un commentaire sur une seule ligne dans *.le café ?

  • Veuillez choisir une réponse qui répond à vos question: comment puis-je le document *.le café des fichiers à générer le javascript contenant de travail JSDoc pour le compilateur de fermeture?
InformationsquelleAutor aztack | 2011-10-20
  1. 3

    Je vous le déconseille cette. JSDoc-ing tous de votre code est un processus laborieux qui est susceptible de produire peu ou pas de bénéficier de la Fermeture du Compilateur. En dehors de Google lui-même, presque personne ne le fait. CoffeeScripters/JavaScripters préfèrent généralement légère à la documentation des outils comme docco.

    Aussi, tandis que le Compilateur de Fermeture a la Google le nom de la marque derrière elle, UglifyJS s'est avéré être le plus efficace minification outil dans de nombreux cas. (jQuery récemment passé à elle.)

    Encore une question: est-il un moyen de conserver un commentaire sur une seule ligne dans *.le café ?

    Oui:

    ### foo ###

    ou

    `//foo`
    • // foo va ajouter un ";" à la fin de la ligne, est-il un moyen de l'enlever?
    • Lorsque utilisé en mode avancé, google closure compiler fournit une compression et la vitesse d'exécution. Voir repères au jsperf.com/testing-code-performance-by-compression-type
    • Il ya de nombreux avantages à JSDoc qui vont au-delà de la Fermeture optimisation du Compilateur, sans doute plus important que de faire une grande recherche de la documentation collectées. Si vous utilisez JSDoc, une bonne IDE code et le type de conseil, de donner des avertissements/erreurs, et de faire @voir/@link navigables. Compte tenu de la racine d'un nombre incalculable de bugs est soit l'absence de signature ou de l'absence de l'adhésion des parties, je dirais que JSDoc est important dans tous les JS, minimisé ou pas (et il y a quelques IDEs tels que PHPStorm qui, heureusement, la digérer en CoffeeScript contexte).
    • Aussi, de ne pas être trop contradictoire, mais comment est-docco à tous les "léger documentation" comme vous dites? Il nécessite des composants tiers, une configuration supplémentaire, une autre compilation routine ajoutés à votre routine, et le pire de tout supplément d'attention par le développeur pour produire de belles grosses pléthorique des commentaires qui ne sont pas fonctionnels dans le contexte du code source d'origine (voir JSDoc arguments ci-dessus).
    • Cette "réponse" ignore la question en faveur d'une opinion personnelle.
    • 1 ce n'est pas une réponse à la question
    • -1 Cela ne répond pas à la question. Tout d'abord, vous semblez complètement à côté du point de jsDoc. Deuxièmement, docco être un "léger outil de documentation" est tiré par les cheveux.

    InformationsquelleAutor Trevor Burnham
  2. 77

    CoffeeScript D'Entrée:

    ### 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 Sortie de windows invite de cmd 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 a une meilleure méthode disponible pour résoudre ce problème.

    • remarque: Coffeescript compilateur ajoute des espaces après le commentaire, par conséquent, certains analyseurs pourriez ne pas reconnaître comme JSDoc, qui est, je pense (à partir de l'expérience avec d'autres doc de l'outillage), censé être exactement la ligne avant de la définition de la méthode commence
    • Cela ne semble plus fonctionner. Avec CoffeeScript 1.6.3 le JavaScript de sortie contient un var cube avant la définition de la fonction qui inhibe JSDoc 3.2.0 pour générer la documentation de la fonction.
    • Travaille toujours pour moi, voir mise à jour de répondre...
    • Cela dit, je n'ai pas essayé JSDoc 3.2.0 - donc, qui pourraient ne pas fonctionner du tout, en fait, que l'intention de ma méthode est de définir la variable avant de la bloquer.
    • "JSDoc-ing tous de votre code est un processus laborieux qui est susceptible de produire peu ou pas de bénéficier de la Fermeture du Compilateur" Citation de ci-dessus. Je ne pouvais pas être plus d'accord. Et les Pseudo-JSDoc-ing CoffeeScript code, en espérant que le résultat sera finalement apte valide JSDoc format des rendements proches de aucun avantage à tous. Peut fonctionner correctement avec certains de libération. Mais "peut" est juste ne vaut pas la peine.
    • Je ne peux pas l'obtenir pour fonctionner avec les méthodes de la classe en CoffeeScript.

    InformationsquelleAutor Billy Moon
  3. 33

    Puisque je ne peux pas répondre directement à Billy ci-dessus, il semble CoffeeScript 1.7.1 a un meilleur support pour ce:

    ###*
# 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) {}
    InformationsquelleAutor mike wyatt
  4. 6

    Vous allez avoir à expérimenter un peu (beaucoup), mais ### commentaires est votre ami.

    Le coffee-script compilateur va garder les commentaires qui utilisent le ### forme (docs ici).

    J'ai essayé de créer un vraiment simple JsDoc fragment d'une fonction à l'aide de la " essayer coffeescript fonction 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 expert en JsDoc, mais j'imagine que l' var foo; déclaration ci-dessus, la fonction va créer un problème. Si vous aviez foo déclaré avant, maybee..

    Il serait bien de heare comment il va.

    InformationsquelleAutor Jacob Oscarson
  5. 0

    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 il est invalide dans JSDoc

    InformationsquelleAutor Li Hanyuan