Le code JavaScript autodocumenté où est l'API des outils Docs?

Question

Ces deux concepts semblent contre-intuitif. Il y a un côté de l'argument qui voit le mal que les commentaires font à la lisibilité et les violations des SEC (si les commentaires sont même tenus à jour). Cependant, retournez la pièce et il y a une nécessité de fournir une bonne documentation de l'API pour votre code pour que les autres peuvent utiliser vos bibliothèques.

Chaque outil (JSDoc, CDRP, etc.) Je l'ai vu qui est conçu pour générer des documents de l'API utilise une quantité extrême de l'espace pour fournir cette documentation. Je dois fournir de la documentation de l'API, ce que je ne ai pas besoin est d'avoir la moitié de mon LOC spécialement formaté des commentaires afin JSDoc peut le lire.

J'envisage actuellement un outil de démarquage de base comme Jekyll et de mettre cette documentation dans un dossier / doc , tout à fait retirer de mon code. Quelqu'un at-il trouvé autre une approche de ce problème qui a travaillé pour eux?

Answer 1

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

Personnellement, je trouve plus pratique d'avoir la documentation API juste à côté du code, car il me permet de garder à jour. De plus, d'autres personnes qui travaillent sur ce code seront en mesure d'avoir la documentation juste au moment où ils en ont besoin, sans avoir à parcourir des fichiers externes. Franchement, je ne vois rien de mal à avoir la plupart des lignes de code qui sont des commentaires. Éditeurs généralement des commentaires couleurs différemment et vous permettre de les ignorer si vous voulez