JavaScript Code auto-documentant où sont les outils API Docs?

Ces deux concepts semblent contre-intuitifs. Il y a un côté de l'argument qui voit le mal que font les commentaires à la lisibilité, et les violations de DRY (si les commentaires sont même tenus à jour). Cependant, retourner la pièce et il est nécessaire de fournir une bonne documentation API pour votre code afin que les autres puissent utiliser vos bibliothèques.JavaScript Code auto-documentant où sont les outils API Docs?

Chaque outil (JSDoc, PDoc, etc.) que j'ai vu qui est conçu pour générer des documents API utilise une quantité extrême d'espace pour fournir cette documentation. J'ai besoin de fournir de la documentation sur l'API, ce dont je n'ai pas besoin, c'est que la moitié de mon LOC soit formatée de façon à ce que JSDoc puisse le lire.

Je considère actuellement un outil de démarquage de base comme Jekyll et de mettre cette documentation dans un dossier/doc, en le supprimant totalement de mon code. Est-ce que quelqu'un d'autre a trouvé une approche à ce problème qui a fonctionné pour eux?

Source

2011-03-17 Drew

Si vous utilisez un script de compression au moment de la construction, vous n'avez vraiment pas à vous soucier des lignes supplémentaires dans votre code. – epascarello

Accepter complètement. Si vous voulez fournir une documentation de bonne qualité, il faut rester avec le code source. Lorsque vous utilisez un fichier compressé en production (ce que vous devez faire de toute façon), les commentaires n'ont aucune importance. – Daff

Pas préoccupé par les fichiers de production, les compresseurs vont l'enlever. Je veux des fichiers lisibles qui ne sont pas des commentaires spécialement formés à 75% juste pour que certains outils puissent les lire. – Drew

Sphinx est un outil de documentation pour de nombreuses langues, ce qui suppose que vous allez écrire votre documentation principalement dans des fichiers externes. Pourtant, il a une extension autodoc qui vous permet d'extraire la documentation des commentaires dans le code.

Personnellement, je trouve plus pratique d'avoir la documentation de l'API juste à côté du code, car cela m'aide à la tenir à jour. De plus, d'autres personnes travaillant sur ce code pourront avoir la documentation juste au moment où ils en ont besoin, sans avoir à parcourir les fichiers externes. Je ne vois franchement rien de mal à avoir la plupart des lignes de code qui sont des commentaires: les éditeurs colorent généralement les commentaires différemment et vous permettent de les ignorer si vous le souhaitez.

Source

2011-03-17 18:06:33 Andrea

Cela semble assez cool en ce qui concerne l'utilisation de fichiers externes. Je voudrais cependant me limiter à la démarque pour les cross-tool, car beaucoup de gens passent à la démarque. Est-ce que cela peut analyser les fichiers JavaScript? – Drew

Je ne l'ai pas essayé, mais autodoc devrait aussi fonctionner avec les fichiers Javascript. – Andrea

JavaScript Code auto-documentant où sont les outils API Docs?

Répondre

Questions connexes