Am Samstag, 11. Dezember 2004 17:13 schrieb Erik Schanze:
Ich habe etwas mit Javadoc bzw. dem Tool doxygen gespielt und die Möglichkeiten gefallen mir schon gut. (kdoc und doc++ wollte den Code nicht akzeptieren)
Kdoc wurde gebaut, als doxygen noch nicht mit Signals/Slots von Qt umgehen konnte, und auch so noch in den Kinderschuhen steckte. Mittlerweile verwendet aber selbst KDE doxygen, und kdoc sollte begraben werden.
Wie sollte man solche Kommentare am besten einbauen? Wie detailliert sollten sie sein?
- Javadoc-Syntax? (Vorteil: Quasi-Standard, aber Javadoc für C++-Code? ;-)
- eine Variante, die Tool XYZ verwendet? (Nachteil: evtl. nicht von anderen Tools verarbeitbar)
Javadoc und Doxygen sollten miteinander verträglich sein. Ich denke, daß doxygen heutzutage Standard ist. Es ist außerdem sehr mächtig, d.h. man kann (wenn man möchte) eigene Makros definieren (z.B. \maintainer zusätzlich zu \author).
- In welche Dateien gehören diese Kommentare? *.cxx oder *.hh?
Ich würde sie immer in die Header reinnehmen. Diese sind ja sowieso immer installiert, während die Sourcen einer Bibliothek meist nicht dazugehören. Für die Doku selbst ist das egal (z.B. Qt ist im Source dokumentiert), aber wer wie ich gern mal per 'grep' durch die Header geht, wird erstere Methode zu schätzen wissen.
Doku ist ja größtenteils für andere gedacht, abgesehen von einer Gedächtnisstütze für sich selbst. Von daher sollte das Ausgabeformat dann auch immer so gebaut sein, daß es mit ähnlichen Projekten übereinstimmt. Also KDE-Dokus im Stil der kdelibs-HTML-Seiten, Java-Dokus im Still der Javadoc-Klassendokus etc. Gtk+/GNOME verwendet docbook-to-html, welches den SGML-Stil 'gtk' kennt, der auch so recht hübsch (und schlicht) aussieht.
Doxygen kann darüberhinaus auch manpages generieren, was nicht sehr übersichtlich aussieht, aber auch von mir häufig verwendet wird (man foo_h). Erspart den Griff zum Browser...
Josef