Tach!
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.
Denn Dokumentation bedeutet für mich, den Sinn bestimmter Funktionen oder Code-Abschnitte zu beschreiben, sowie das Zusammenspiel der einzelnen Komponenten. Die sogenannten Dokuemntations-Systeme wie etwa JSDoc können aber bestenfalls auf Funktions- oder Objektebene die Schnittstellen beschreiben. Das ist meines Erachtens ein Teil der Dokumentation, aber nur ein sehr kleiner.
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.
/**
* Kurztext
*
* Langtext
*
* @irgendwelche_parameter
*/
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. 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. Es ist ja noch nicht mal gesagt, dass der Code abseits der Schnittstellen für die Verwender sichtbar ist (auch Javascript kann durch Verunstalter nahezu unlesbar gemacht werden).
dedlfix.