JavaScript-Selbstdokumentationscode Wo sind die API-Dokument-Tools?

Question

Diese beiden Konzepte scheinen kontraintuitiv zu sein. Es gibt eine Seite des Arguments, bei dem der Schaden zu den Kommentaren zur Lesbarkeit und Verstößen gegen die Trockenheit sieht (wenn die Kommentare überhaupt auf dem neuesten Stand gehalten werden). Drehen Sie jedoch die Münze um und es besteht die Notwendigkeit, eine gute API -Dokumentation für Ihren Code zu liefern, damit andere Ihre Bibliotheken verwenden können.

Jedes Tool (JSDOC, PDOC usw.), das ich gesehen habe und das für die Generierung von API -Dokumenten ausgelegt ist, verwendet extreme Menge an Platz, um diese Dokumentation bereitzustellen. Ich muss eine API -Dokumentation bereitstellen. Ich brauche nicht, dass die Hälfte meines LOC speziell formatiert wird, damit JSDOC es lesen kann.

Ich denke derzeit über ein grundlegendes Markdown -Tool wie nach Jekyll und diese Dokumentation in den A /DOC -Ordner einzulegen und sie vollständig aus meinem Code zu entfernen. Hat jemand anderes einen Ansatz für dieses Problem gefunden, das für sie funktioniert hat?

Answer 1

Sphinx ist ein Dokumentationsinstrument für viele Sprachen, das davon ausgeht, dass Sie Ihre Dokumentation hauptsächlich in externen Dateien schreiben. Trotzdem hat es eine autodoc Erweiterung, mit der Sie Dokumentation aus den Kommentaren im Code extrahieren können.

Ich persönlich finde es bequemer, die API -Dokumentation in der Nähe des Code zu haben, da ich sie auf dem neuesten Stand halte. Darüber hinaus können andere Personen, die an diesem Code arbeiten, die Dokumentation nur dann haben, wenn sie sie benötigen, ohne externe Dateien durchsuchen zu müssen. Ich sehe ehrlich gesagt nichts falsch daran, die meisten Codezeilen zu haben, die Kommentare sind: Editoren färben normalerweise anders und erlauben Sie, sie zu ignorieren, wenn Sie möchten.