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
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.
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.
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.
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. ;-)
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.
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
Bitte melde dich an um einen Beitrag zu schreiben. Anmeldung ist kostenlos und dauert nur eine Minute.
Bestehender Account
Schon ein Account bei Google/GoogleMail? Keine Anmeldung erforderlich!
Mit Google-Account einloggen
Mit Google-Account einloggen
Noch kein Account? Hier anmelden.