Wo die Doxygen-Kommentare hingeschrieben werden, hängt vom Typ der
Dokumentation ab, die erstellt werden soll. Die Dokumentation besteht
aus Teilen, die sich mit dem Was, und anderen Teilen, die sich mit dem
Wie beschäftigen:
Was-Dokumentation:
- Was tut die Funktion?
- Welche Daten gehen in die Funktion hinein, welche kommen heraus?
- Wofür steht ein Datentyp, was kann man damit anfangen?
- Ergänzende Informationen zur Verwendung der Funktionen und
Datenstrukturen
- ...
Wie-Dokumentation:
- Wie ist eine Funktion oder eine Datenstruktur implementiert?
- Warum wurde sie so implementiert?
- Welche Algorithmen und Programmierkniffe kommen zum Einsatz?
- ...
1. API-Dokumentation
Sie dokumentiert eine Programmbibliothek und richtet sich an den
Anwender dieser Bibliothek, also einen Programmierer auf höherer Ebene.
Darin sind alle Funktionen und Datenstrukturen beschrieben, die die
Bibliothek dem Anwender zur Verfügung stellt. Soll die Dokumentation
kein reines Nachschlagewerk (Referenz) sein, enthält sie zusätzlich
übergreifende Informationen, wie z.B.
- Informationen über das Zusammenwirken der Funktionen und
Datenstrukturen
- allgemeine Hinweise zur effektiven Nutzung der Bibliothek
- Programmbeispiele, die sich auf mehrere Funktionen oder
Datenstrukturen beziehen
- usw.
Die formale Beschreibung des API besteht aus den C-Deklarationen in den
vom Anwender genutzten header-Files. Da zwischen diesen und der
textuellen Beschreibung der dem Anwender zur Verfügung gestellten
Funktionen und Datenstrukturen eine 1:1-Beziehung besteht, ist es
sinnvoll, die textuellen Beschreibungen (also die Doxygen-Kommentare) in
dieselben Header-Files zu schreiben.
Diese Kommentare enthalten typischerweise nur Was-, aber keine
Wie-Informationen. Das Wie ist für den Anwender nur in Ausahmefällen von
Interesse, bspw. dann, wenn zwei Funktionen Ähnliches tun, aber
unterschiedliche Algorithmen verwenden. Dann kann die Kenntnis der
Algorithmen eine Entscheidungshilfe für die Auswahl der für den
aktuellen Anwendungsfall bestgeeigneten Funktion sein. Eine
Kurzbeschreibung der Algorithmen kommt dann ebenfalls in die
Header-Files.
Ebenfalls von geringem Interesse für den Anwender sind Hilfsfunktionen
und Datenstrukturen, die ausschließlich intern verwendet werden. Diese
sollten nicht als C-Code in den vom Anwender verwendeten Header-Files
auftauchen und sollten in der API-Dokumentation auch nicht dokumentiert
zu werden, da sie eher zur Verwirrung als zum Verständnis beitragen.
Die übergreifenden Informationen sollten auch in einer übergeordneten
Datei stehen. Man schreibt sie deswegen entweder in das zentrale
Header-File der Bibliothek, oder — wenn die Informationen zu umfangreich
sind — in eine oder mehrere eigene Dateien, die nur Doxygen-Kommentare
enthalten.
Bei größeren APIs kann auch eine Hierarchisierung — sowohl der
Header-Files als auch der Erläuterungen — in mehreren Ebenen sinnvoll
sein. Doxygen bietet auch hier Unterstützung.
2. Entwicklerdokumentation
Sie dokumentiert ein Anwendungsprogramm oder eine Programmbibliothek und
richtet sich an die aktuellen und zukünftigen Entwickler dieser
Software.
Der Inhalt ist ähnlich dem der API-Dokumentation, enthält aber außer dem
Was auch das Wie, also bspw. die in den Funktionen verwendeten
Algorithmen. Die Wie-Dokumentation schreibt man sinnvollerweise dorthin,
wo die Algorithmen implementiert sind, nämlich in die C-Files. Wo man
die Was-Dokumentation hinschreibt (ob in die Header- oder die C-Files),
ist eher Geschmacksache. Für eine reine Entwicklerdokumentation würde
ich der leichteren Handhabbarkeit wegen alle Kommentare in die C-Files
schreiben (aber siehe "3. Kombinierte Dokumentation").
Für den Entwickler ist natürlich auch die Beschreibung von Interna
wichtig, deswegen stehen diese ebenfalls dort, wo die entsprechenden
Funktionen und Datentypen deklariert bzw. implementiert sind.
Ebenso wie die API-Dokumentation kann auch die Entwicklerdokumentation
hierarchisiert werden.
3. Kombinierte Dokumentation
Für eine Programmbibliothek möchte man meist zwei Dokumentationen
erstellen, eine für die Anwender und eine für die Entwickler der
Bibliothek. Es ist bei entsprechender Organisation leicht möglich, aus
einem Satz Doxygen-Kommentare sowohl die API- als auch die
Entwicklerdokumentation zu erzeugen:
Man schreibt dazu das, was den Anwender interessiert, gemäß Abschnitt 1
in die vom Anwender genutzten Header-Files. Die Wie-Dokumentation für
den Entwickler kommt in die C-Files und die Was-Dokumentation interner
Funktionen oder Datenstrukturen in ausschließlich intern genutzte
Header-Files oder (je nach Gechmack) ebenfalls in die C-Files.
Je nachdem welcher Dokumentationstyp gewünscht wird, lässt man Doxygen
entweder nur über die Anwender-Header-Files oder über alle
Quellcode-Files laufen. Dabei ergibt sich die Trennung zwischen den für
den jeweiligen Doxygen-Lauf benutzten Dateisätzen aus den Dateinamen
(Extensions) oder (besser) aus den Verzeichnissen, in denen die Dateien
liegen.
Besteht die Dokumentation einer Funktion aus zwei Teilen, nämlich aus
dem Was-Teil im Anwender-Header-File und dem Wie-Teil im C-File,
kombiniert Doxygen für die Entwicklerdokumentation die beiden Teile so,
dass direkt hintereinander zuerst der Header-File-Kommentar und danach
der C-File-Kommentar aufgeführt wird, wodurch sich automatisch die
richtige Reihenfolge von der Abtstraktion hin zum Detail ergibt.
Huch, das ist wieder einmal lang geworden ;-) Ich hoffe, dass trotzdem
jemand etwas damit anfangen kann.
