web-dev-qa-db-fra.com

Comment créer facilement un démarquage convivial Github pour les fonctions JavaScript documentées?

Je veux pouvoir prendre des commentaires JSDoc comme ceci n'importe où dans la source JavaScript (même imbriqué sur 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 un moyen facile de produire une démarque agréable:

##`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 auquel cette fonction est accessible. Ou s'il s'agit d'une fonction anonyme ou d'une fonction privée (qui, pour une raison quelconque, devrait être dans un doco public, est-ce même logique?), Utilisez une autre convention pour le désigner. Peut être

##_private_function_ `something(whatever,callback)`

  and

##_anonymous_function_`(whatever,callback)`

Il ne doit pas être exactement ce format, juste quelque chose qui a l'air bien sur Github et qui a du sens. L'outil idéal serait suffisamment intelligent pour pouvoir prendre du code comme Moustache.js et produire une bonne sortie. Et ce serait encore mieux s'il peut gérer de nombreux fichiers source et produire un document en sortie, ou un ensemble de documents liés en fonction de la configuration.

Et il serait préférable que cela soit fait d'une manière qui puisse être entièrement et facilement incluse dans un dépôt git afin que les gens n'aient pas besoin de mettre en place une chaîne d'outils très spécifique pour mettre à jour le doco. Ou exigez au moins une chaîne d'outils minimale.

Oh, et un poney.

Options existantes

JSDoc , plus une sorte de HTML -> conversion de démarque

JSDoc est assez bon. Mais je n'arrive pas à le faire fonctionner correctement avec les modules. Ou plutôt, c'est un plus gros tracas qu'il ne devrait l'être à mon humble avis. Je ne devrais pas avoir besoin d'ajouter une balise supplémentaire pour nommer la fonction. J'ai essayé @export et @name et j'ai toujours du mal à le faire apparaître dans le document final comme je le voudrais. Si quelqu'un peut pointer vers une source commentée JSDoc qui contient des modules et qui fonctionne bien, cela pourrait aider. Mise à jour: JSDoc v3 semble en fait beaucoup mieux avec les modules que v2 donc cela pourrait être un meilleur ajustement.

Même si je pouvais obtenir la sortie JSDoc comme je le souhaitais, je devrais convertir du HTML en markdown. Je n'arrive pas à trouver un bon outil pour ça, existe-t-il?

Docdown

J'ai joué un peu avec Docdown mais le fait que ce soit PHP est une sorte de non-starter pour moi ...

YUIDoc , plus la conversion

En fait, je n'ai pas joué avec YUIDoc mais ça a l'air ok. Pourtant, j'aurais besoin d'un convertisseur. Traite-t-il facilement les modules et évite-t-il d'avoir à fournir explicitement le nom de la fonction et le nom de l'exportation?

Dox , plus des modèles de démarques

Dox produit du JSON en sortie, vous devez donc le marier à de bons modèles de démarques et inclure un moteur de modèle pour générer les documents. Quelqu'un a-t-il rassemblé un ensemble de ces modèles de manière utile?

jGrouse , plus la conversion

Fonctionne avec ANT. Prochain...

ScriptDoc ...

Cela existe-t-il encore? Semble faire partie du studio Aptana, ce serait donc un non-démarreur ... Aptana ne semble pas avoir d'informations à ce sujet. Mais ScriptDoc.org a des informations intéressantes sur le crack, si cela est utile ...

Pdoc

Pdoc est Ruby mais cette chaîne d'outils n'est pas rare donc ce n'est pas un gros problème. Vous pouvez fournir vos propres modèles alors peut-être qu'il y a déjà de bons modèles de démarque. Je n'ai pas joué avec. .. est-ce utile? Y a-t-il de bons modèles de démarques?

Autre chose?

Quoi d'autre est là-bas?

Faire votre propre!

Après avoir joué avec JSDoc pendant quelques heures pour essayer de le faire fonctionner comme je le voulais, j'ai abandonné et j'ai écrit ma propre solution rapide et sale en Java pour CharFunk , un unicode Bibliothèque JavaScript sur laquelle je travaille. Cela fonctionne assez bien pour ce dont j'ai besoin, bien qu'il ne soit pas encore proche de l'usage général.

Donc.....

Est-ce un besoin non satisfait ou est-ce juste moi?

javascriptgithubmarkdownjsdoc
60
jwl

Avez-vous essayé jsdox ?

C'est un générateur node.js jsdoc to markdown.

13
Steven de Salas

J'utilise jsdoc-to-markdown ..

écrire du code documenté:

/**
a quite wonderful function
@param {object} - privacy gown
@param {object} - security
@returns {survival}
*/
function protection(cloak, dagger){}

obtenir des documents de démarque:

$ jsdoc2md example/function.js

#protection(cloak, dagger)
a quite wonderful function

**Params**

- cloak `object` - privacy gown
- dagger `object` - security

**Returns**: `survival`

Ces projets ont des fichiers Lisez-moi rendus par jsdoc2md:

18
Lloyd

markdox peut générer des documents de démarque à partir du code javascript.

7
user2367031

jsDox. https://github.com/sutoiku/jsdox Analyse complète en utilisant UglifyJS

Mox. https://github.com/tjchaplin/mox Plusieurs exemples/modèles prêts à l'emploi.

Les deux gèrent les formats JSDoc/Dox. Les deux ont un développement actif. Pour moi, Mox gagne grâce à l'exemple de suite.

3
Chris Buck

D'ACCORD. Après quelques délibérations avec moi-même, j'irais avec le moteur de modélisation DOX + Underscore/Whats JS sur Node.

Ça devrait être assez simple. Vous pouvez, éventuellement, même brouiller dans Grunt ou similaire et le faire exécuter sous une tâche de surveillance.

Dox, d'après ce que je me souviens, est relativement léger et possède un package npm (IIRC).

MISE À JOUR: Je pense, après une certaine expérience, que je voudrais changer ma réponse à YUIDoc.

2
ZenMaster

J'avais besoin de créer une documentation API à partir de JSDoc qui devrait être facile à utiliser et prend également en charge les piles frontales modernes. Certaines des bibliothèques mentionnées ont des problèmes avec le code JS transpilé en babeljs, vous devez donc transpiler votre code avec des commentaires temporairement juste pour générer votre documentation de démarque.

Pour un tel cas d'utilisation, j'ai trouvé http://documentation.js.org/ très utile car ils ont un support intégré pour les configurations BabelJs donc il s'occupe de générer du démarque (JSON, HTML) à partir de vos JSDocs.

0
Fer To

Essayez d'utiliser Verbe . Dans le cas d'utilisation le plus simple, Verb créera un fichier Lisez-moi à partir d'un modèle en utilisant les données de package.json.

Mais verb a également des fonctionnalités avancées si vous devez générer des tables des matières de plusieurs pages, ou créer des assistants personnalisés, etc.

En ce qui concerne la documentation de l'API, voir ceci exemple readme généré à l'aide des commentaires de code de index.js. Cliquez sur les titres, ceux-ci sont également générés automatiquement. Utilisez cette aide intégrée pour générer des documents API à partir du chemin de fichier spécifié. Vous pouvez également utiliser des modèles globaux pour extraire des documents de plusieurs fichiers.

Verb va construire un .verb.md sans aucune configuration. Mais si vous en avez besoin de plus, vous pouvez utiliser un verbfile.js

0
jonschlinkert