Dokumentation: doxygen? Natural Docs?

[Detlev T. (detlevt)]

Hallo Leute,

nachdem ich mich letztens wieder über einen Satz der Art "Die 
Beschreibung der API findet ihr in den Quelltexten" geärgert habe, will 
ich jetzt erst einmal den Balken aus meinem eigenen Auge ziehen und 
meine eigenen Werke besser dokumentieren. Mir gefällt dabei die Idee, 
mit Hilfe von Dokumentationssystemen das quasi beim Programmieren gleich 
mit zu erledigen.

Gefunden habe ich bisher die Programme doxygen und Natural Docs. Und 
habe gelernt, dass die für mich als Mensch bislang nur schwer 
verständlichen Beschreibungen im Quelltext anderer Leute wohl daher 
kommen, dass diese offenbar für doxygen erstellt wurden. Das gefällt mir 
also schon einmal nicht.

Besser gefällt mir da die Idee von Natural Docs. Die Kommentare zur 
Beschreibung im Quelltext sind human readable, dafür bietet es viel 
weniger Möglichkeiten als doxygen, z.B. nur HTML als Ausgabeformat. Mir 
würde das aber eigentlich reichen.

Mir fällt aber auf, dass dieses Programm hier fast gar nicht erwähnt 
wird. Deshalb meine Fragen an euch: Habt ihr schon Erfahrung damit 
gemacht? Gibt es einen Grund, dass ihr es (nicht mehr?) einsetzt? Kommt 
später das dicke Ende? Was gibt es vielleicht sonst noch an Programmen, 
die ich mir anschauen sollte? Sie sollten unter Linux ausführbar sein.

Es geht im wesentlichen um C-Quellcode für avr-gcc. Es handelt sich um 
Hobbyprojekte unter GPL. Das heißt, es ist auch immer der Quelltext 
selbst verfügbar und es gibt keine Auftraggeber, die irgendwelche 
Vorgaben machen.

Vielen Dank für eure Antworten.

Gruß, DetlevT

[MaWin (Gast)]

Wenn ein Projekt quasi fertig ist, kannst du simpel in Word oder sonst 
einem Texteditor eine sinnvolle Dokumentation erstellen.

Man holt die Info per Copy & Paste.

Wenn sich dein Projekt noch entwickelt, ist dadurch aber ständige 
Überarbeitung (Neuerstellung) notwendig.
Zu glauben, daß ein Extraktor aus dem Quelltext, der einfach 300 Seiten 
Papier raushaut, damit irgendetwas wie "Dokumentation" erstellt, ist ein 
grandioser Fehlschluss.
Zur Doku gehört unter anderem genau das, was im Quelltext nicht drin 
steht, und was du auch nicht in endlosen Kommentarblöcken einpflegen 
möchtest.

Unsere Erfahrung mit doyxgen sind katastrophal. Natural Docs kenn ich 
nicht. Gute Dokumentationen wurden von Knuth mit dem WEB Programm 
erstellt. Obwohl das Programm sicher nicht mehr zeitgemäss ist, sind die 
Ergebnisse in den letzten 30 Jahren wohl kaum übertroffen worden.

[Simon K. (simon)]

Ich benutze selten mal Doxygen, wenn überhaupt. Das geht aber relativ 
einfach. für Eclipse gibt es auch ein Plugin, womit du .doxyfiles 
erstellen kannst (Die Konfigurationsdateien).

Ansonsten: Stimmt, wenn man die Doxygen Syntax nicht kennt, ist es 
schwieriger die Kommentare zu lesen.

[eklige Tunke (Gast)]

Detlev T. schrieb:
> Besser gefällt mir da die Idee von Natural Docs. Die Kommentare zur
> Beschreibung im Quelltext sind human readable, dafür bietet es viel
> weniger Möglichkeiten als doxygen, z.B. nur HTML als Ausgabeformat. Mir
> würde das aber eigentlich reichen.
Öhm, ich kenne Natural Docs nicht, aber doxygen ist definitv auch 
menschenlesbar. Beim kurzen über Natural Docs schauen, würde ich doxygen 
sogar als lesbarer empfinden, da dort mit @ oder \ (usw) die 
Signalwörter leichter zu erkennen sind...
Da ich mich nur mit doxygen beschäftigt habe, würde es immer auf 
selbiges hinauslaufen.

@ MaWin
Eine zusätzlich Doku gehört natürlich auch dazu. Für privat und nur 
dür mich würde mir doxygen genügen.

[eklige Tunke (Gast)]

Simon K. schrieb:
> Ansonsten: Stimmt, wenn man die Doxygen Syntax nicht kennt, ist es
> schwieriger die Kommentare zu lesen.
Naja, das meiste wie \param, \return usw. erklärt sich von selbst. ;-)

[Simon K. (simon)]

Schon. Aber es hinder einem doch am Lesen, weil es eben kein 
zusammenhängender Text ist.
Bei Natural Docs sind die Schlüsselwörter nicht extra markiert, wenn ich 
das jetzt richtig gesehen habe. Da kannst du quasi nen Text schreiben 
mit "Function: XYZ Returns: bla" und der kann das dann interpretieren.

[Hannes J. (Firma: _⌨_) (pnuebergang)]

Wenn man nicht schreiben kann, kein Talent hat oder nicht schreiben 
will, dann nützt einem das schönste Tool nichts. Wer es kann, bekommt 
gute Dokumentation hin, egal ob mit Doxygen oder Notepad. Wer es nicht 
kann, produziert den üblichen Mist.

Ich würde keine Gedanken auf das Tool verschwenden, sondern darauf 
Schreiben zu lernen