JSDoc Tags gleich? widersprüchlich?

[MB]

Guten Sonntag,

wie sinnvoll ist es mit JSDoc den Sourcecode zu dokumentieren? Ich frage deswegen da es teileweise tags gibt die das gleiche bedeuten oder ähnliches. z.B. @namespace, knn ich mit @constructor gleich bleibent verwenden oder @access, @inner, @static, @protected gleich mit **@memberof" oder @member, @kinde.

Ich müsste da für jede Zeile Code zwei, drei tags verwenden. Ich kann mir schwervorstellen dass das sinn und zweck dieser Docs ist

JSDoc Syntax bietet für mich eine sehr große Hilfestellung. hab aber noch nich mit dieser dokumentation gearbeitet höchstens in JavaDoc.

mfg MB

[Der Martin]

Hallo,

wie sinnvoll ist es mit JSDoc den Sourcecode zu dokumentieren?

IMO überhaupt nicht. 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.

So long,
 Martin

[dedlfix]

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.

[Der Martin]

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

[dedlfix]

Tach!

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.

Du meinst also eine allgemeine Dokumentation abseits vom Code, sowas was in Dokumenten wie readme.txt zu stehen kommt? Aber selbst dann willst du sicher nicht, dass die Schnittstellen nicht im Code dokumentiert sind. Also, ich verstehe immer noch nicht, was an *Doc als Teil der Dokumentation nicht sinnvoll sein soll.

dedlfix.

[Der Martin]

Moin,

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.

Du meinst also eine allgemeine Dokumentation abseits vom Code, sowas was in Dokumenten wie readme.txt zu stehen kommt?

ja, zum Beispiel.

Aber selbst dann willst du sicher nicht, dass die Schnittstellen nicht im Code dokumentiert sind. Also, ich verstehe immer noch nicht, was an *Doc als Teil der Dokumentation nicht sinnvoll sein soll.

Als Teil sehr wohl, das ist okay. Hab ich ja selbst mehrfach betont. Mir sind aber schon öfters Softwarepakete in die Hände gefallen, wo eine derartige, automatisch erstellte Dokomentation alles war. Ist ja auch verführerisch, dieses beruhigende Gefühl, man hätte schon was getan.
Damit allein fängt man aber als Nutzer nicht viel an. Das ist so, als solle man ein tolles Essen zaubern, denkt sich etwas aus, schreibt die Einkaufsliste dazu und meint dann, man sei fertig.

So long,
 Martin

[dedlfix]

Tach!

Mir sind aber schon öfters Softwarepakete in die Hände gefallen, wo eine derartige, automatisch erstellte Dokomentation alles war. Ist ja auch verführerisch, dieses beruhigende Gefühl, man hätte schon was getan.

Das ist aber ein allgemeines Problem und keins der *Doc-Systeme. Als Entwickler kennt man sein Produkt in- und auswändig und weiß, wie die Dinge funktionieren. Die anscheinend meisten tun sich jedoch nicht nur dabei sehr schwer, Dinge aus anderen Perspektiven zu betrachten und können sich nicht so richtig vorstellen, welche Informationen ein Außenstehender benötigt.

Telefonnummer
|___________________________________________________________________|
Geben Sie eine Telefonnummer ein.

Das ist die Art Dokumentation, die man als Anwender nicht braucht. Es ist offensichtlich, dass man in das Feld „Telefonnummer“ eine Telefonnummer eingeben soll. Es ist jedoch nicht offensichtlich, welche Schreibweise das Programm erwartet. Oder wo man gegebenenfalls die Information findet, die das Programm benötigt.

dedlfix.

[Der Martin]

Hallo,

Mir sind aber schon öfters Softwarepakete in die Hände gefallen, wo eine derartige, automatisch erstellte Dokomentation alles war. Ist ja auch verführerisch, dieses beruhigende Gefühl, man hätte schon was getan.

Das ist aber ein allgemeines Problem und keins der *Doc-Systeme.

korrekt: Man benutzt ein Hilfsmittel, das einen glauben lässt, damit sei alles getan. Etwa so, als würde man ein kleines elektronisches Gadget anbieten, und die Bedienungsanleitung erschöpft sich in einer Abbildung mit zwei, drei Worten zu jeder Taste.

Als Entwickler kennt man sein Produkt in- und auswändig und weiß, wie die Dinge funktionieren. Die anscheinend meisten tun sich jedoch nicht nur dabei sehr schwer, Dinge aus anderen Perspektiven zu betrachten und können sich nicht so richtig vorstellen, welche Informationen ein Außenstehender benötigt.

Das ist IMO wieder ein anderes Problem: Die Unfähigkeit, Dinge aus der Perspektive eines Uneingeweihten zu betrachten.

Telefonnummer
|___________________________________________________________________|
Geben Sie eine Telefonnummer ein.

Das ist die Art Dokumentation, die man als Anwender nicht braucht. Es ist offensichtlich, dass man in das Feld „Telefonnummer“ eine Telefonnummer eingeben soll. Es ist jedoch nicht offensichtlich, welche Schreibweise das Programm erwartet.

Genau. Oder wessen Telefonnummer. ;-)

Ciao,
 Martin