Hallo,
wie sinnvoll ist es mit JSDoc den Sourcecode zu dokumentieren?
IMO überhaupt nicht.
Wie so oft kommt es darauf an, was man erreichen möchte.
ja, das ist klar.
Eines der Ziele der *Doc-Systeme ist es, eine maschinenlesbare Dokumentation anzubieten für die Werte, die die Maschine nicht selbst aus dem Code lesen kann. Ein anderes Ziel ist, die Dokumentation im Code pflegen zu können und daraus Dokumentsmedien erzeugen zu können. Auch den Sinn kann man damit dokumentieren. Dafür eignen sich die Felder für Kurz- und Langtext.
Aber es ändert nichts daran, dass damit nur Dokumentation auf, sagen wir, molekularer Ebene erzeugt wird. Schnittstellen, Funktion von einzelnen Modulen. Das erfüllt aber bei weitem nicht den Anspruch, den ich an Dokumentation stellen würde.
Ich sehe da grad nicht, inwieweit sie überhaupt nicht sinnvoll seien. Dokumentationen für einzelne Codezeilen und Abschnitte kann man ja nebenbei bei Bedarf einfügen.
Als Kommentare im Code, ja, okay.
Diese zu dokumentieren ist auch nicht Aufgabe von *Doc, denn Dokumentation im Code hat ein anderes Publikum als die Dokumentation der Schnittstellen. Und in auf herkömmliche Art erstellten Dokumentationen für Verwender werden wohl auch nicht die Interna erscheinen.
Das ist ja auch nicht das, was ich vermisse bzw. fordere. Der wichtigste Teil der Dokumentaion ist für mich, wie ich schon sagte, das Zusammenspiel vieler Funktionen, Objekte oder Methoden. Und das ist mit einer Beschreibung der Schnittstellen eben nicht getan, die ist nur ein kleiner Teil davon.
So long,
Martin
Nothing travels faster than the speed of light with the possible exception of bad news, which obeys its own special laws.
- Douglas Adams, The Hitchhiker's Guide To The Galaxy