Je veux être en mesure de prendre JSDoc les commentaires de ce genre n'importe où dans le code JavaScript de la source (même imbriquée plusieurs couches de fonctions dans un module ou même des fonctions anonymes):
/**
* Used to do some important thing that needs doing that works like xyz.
* @param {String} whatever - some string that has some purpose
* @param {Function} callback - a function that needs to be run
* @returns {Boolean} whether or not something happened
*/
function something(whatever, callback) {
...
et avoir une certaine manière simple de produire de nice markdown:
##`root.something(whatever,callback)`
Used to do some important thing that needs doing that works like xyz.
*Parameters*
`whatever {String}` some string that has some purpose
`callback {Function}` a function that needs to be run
*Returns*
`{Boolean}` whether or not something happened
Où "root" est l'espace de noms dans lequel cette fonction est accessible. Ou si c'est une fonction anonyme ou d'une fonction privée (qui pour une raison quelconque devrait être en public doco, est-ce que même un sens??), utiliser une autre convention pour désigner cela. Peut-être
##_private_function_ `something(whatever,callback)`
and
##_anonymous_function_`(whatever,callback)`
Il n'a pas à être exactement ce format, juste quelque chose qui semble bon sur Github et de la logique. L'outil idéal serait assez intelligent pour être en mesure de prendre un code comme Mustache.js et produire du bon de sortie. Et un bon supplémentaire serait si il peut gérer beaucoup de fichiers source et de produire un document de sortie, ou un ensemble de documents en fonction de la configuration.
Et il serait mieux si cela a été fait d'une manière qui peut être facilement et entièrement inclus dans un repo git, de sorte que les gens n'ont pas besoin de configurer un hautement spécifique de la chaîne de traitement pour la mise à jour de la doco. Ou ne nécessitent qu'un minimum de la chaîne d'au moins.
Oh, et un poney.
Options existantes
JSDoc, plus une sorte de HTML> démarque de conversion
JSDoc est assez bonne. Mais je n'arrive pas à faire fonctionner correctement avec des modules. Ou plutôt, c'est un plus de tracas que ce qu'il doit être, à mon humble avis. Je ne devrais pas avoir besoin d'ajouter une balise de nom de la fonction. J'ai essayé de la @exportation et @nom et ont encore du mal à la faire apparaître dans le dernier doc de la façon que je le voudrais. Si quelqu'un peut pointer vers un JSDoc a commenté la source qui a des modules en elle et est bien fait, ça pourrait aider. Mise à jour: JSDoc v3 semble en fait beaucoup mieux avec des modules que v2 donc cela pourrait être un meilleur ajustement.
Même si je pouvais obtenir JSDoc de sortie comme je veux, j'avais besoin de convertir en HTML au format markdown. Je n'arrive pas à trouver un bon outil pour cela, ne peut-on exister?
Docdown
J'ai joué un peu avec Docdown mais le fait que c'est PHP est une sorte de nonstarter pour moi...
YUIDoc, en plus de la conversion
En fait je n'ai pas joué avec YUIDoc mais ça a l'air ok. Encore, j'aurais besoin d'un convertisseur. Ne traite facilement les modules et éviter d'avoir à fournir le nom de la fonction et de l'exportation explicitement le nom?
Dox, plus de démarque des modèles
Dox produit JSON comme il est de sortie, alors vous auriez besoin de les marier à des bonnes démarque des modèles, et plus incluent un moteur de template pour générer les documents. Quelqu'un a mis en place un ensemble de ces modèles d'une manière utile?
jGrouse, en plus de la conversion
Fonctionne avec ANT. La prochaine...
ScriptDoc...
Cette même existe plus? Semble faire partie de Aptana studio alors que ce serait une nonstarter... Aptana ne semble pas du tout d'info sur lui. Mais ScriptDoc.org a quelques informations intéressantes sur la fissure, si c'est utile...
Pdoc
Pdoc est Ruby, mais que la chaîne n'est pas rare que ce qui n'est pas un énorme problème. Vous pouvez fournir vos propres modèles alors peut-être il y a déjà quelques bonnes markdown ceux. Je n'ai pas joué avec elle... est-il utile? Sont bons de réductions de prix des modèles là-bas?
Quelque chose d'autre?
Quoi d'autre est là?
Faire votre propre!
Après de déconner avec le JSDoc pour quelques heures à essayer de le faire fonctionner comme je le souhaitais, j'ai renoncé et a écrit de ma propre rapide et sale de la solution en Java pour CharFunk, unicode bibliothèque JavaScript j'ai travaillé. Il fonctionne assez bien pour ce que j'ai besoin qu'il n'est pas près à usage général, encore.
Donc.....
Est-ce un besoin ou est-ce juste moi?
