Doxygen in KDevelop-Projekten verwenden
Dieses Dokument beschreibt die Verwendung von Doxygen in
KDevelop-Projekten.
Hinweis:
Für das GVim-Doxygen-Plugin stehen unter
http://stud-in.fh-swf.de/Matthias.Faulstich/tools/vim_doxygen_qt4
Templates für C++ - Klassen zur Verfügung.
Einleitung
Das Dokument versteht sich nicht als eine allgemein gültige
Doxygen-Dokumentation. Vielmehr beschränkt es sich auf die Beschreibung der
erforderlichen Einstellungen, Doxygen Kommentare und Doxygen Schlüsselwörter,
die zur Erstellung einer HTML-Dokumentation eines C++ Projekts erforderlich
sind. Das Ergebnis einer Vorgehensweise nach dieser Anleitung entspricht in
Umfang und Inhalt etwa einer javadoc-Dokumentation.
Eine Dokumentation nach dieser Anleitung entspricht den Anforderungen an
eine Dokumentation im Praktikum "Programmierung grafischer
Benutzeroberflächen" des Studiengangs Angewandte Informatik der
Fachhochschule Südwestfalen in Iserlohn.
Mit diesem Anspruch bleibt eine nach dieser Anleitung erzeugte
Dokumentation hinter den Möglichkeiten von Doxygen zurück. Für weiterführende
Beschreibungen sei hier auf die unterschiedlichen HOWTOs verwiesen, die im
Internet reichlich verfügbar sind.
Projekteinstellungen für Doxygen
Üblicherweise wird Doxygen durch die Einstellungen in einer
Konfigurationsdatei gesteuert. Diese muss bei der Verwendung von KDevelop
nicht manuell erzeugt werden. Unter dem Projekteinstellungen in KDevelop
(Projekt / Projekt-Einstellungen) befindet sich ein Dialogfenster
für die projektbezogenen Doxygen-Einstellungen. Wählen Sie auf der linken
Seite Doxygen.
Nehmen Sie im Dialogfenster folgende Änderungen vor:
| Registerkarte |
Option(en) |
| Projekt |
| Ausgabepfad |
doc
Setzen Sie hier unbedingt
den relativen
Pfad zum Quelltextverzeichnis! |
| Ausgabesprache |
<Anpassen an die bei der Dokumentation verwendete
Sprache> |
| ( ) vollständigen Pfadnamen benutzen |
deaktivieren! |
|
| Erstellen |
(x) Statische Member ausgeben |
| Meldungen |
| (x) Warnung ausgeben, wenn Funktionsparameter
nicht dokumentiert sind |
aktivieren! |
|
| Input |
| Eingabedateien und -Ordner |
src
Setzen Sie hier unbedingt
den relativen
Pfad zum Quelltextverzeichnis! |
|
| Index |
(x) Erstelle alphabetischen Index |
| HTML |
(x) Inhaltsverzeichnis erweitern
(x) Baumansicht erstellen |
| LaTeX |
( ) LaTeX erstellen |
| XML |
( ) Erstelle XML |
Hinweis:
Wenn Sie CVS oder eine andere Versionsverwaltung verwenden, aktualisieren
Sie Ihrem CVS-Repository die Datei
<projektname>.kdevelop
mit commit. Anderenfalls gehen die Einstellungen für Doxygen
verloren!
Dokumentation der Quelltexte
Ziel einer Dokumentation
Dokumentation, wie sie mit Doxygen erzeugt wird, dient dazu, Teamkollegen
oder fremde Entwickler, die die entwickelten Klassen verwenden sollen /
dürfen über die Möglichkeiten der betreffenden Klasse zu informieren. Man
kann die Dokumentation daher als eine "Bedienungsanleitung" verstehen. Aus
dieser Sicht wird die Art und der Umfang der erforderlichen Dokumentation
deutlich.
Aus diesem Grund müssen alle Klassenbestandteile dokumentiert werden,
- die public deklariert sind, da diese von einem Objekt
der Klasse oder über den Klassennamen selbst (static) verwendet werden
können.
- die protected deklariert sind, da diese von
abgeleiteten Klassen verwendet bzw. überschrieben werden können.
Klassenkommentare
Klassen werden in der Header-Datei
(*.h) einer Klasse kommentiert.
Der Kommentar umfasst:
- Kurzbeschreibung
- Zweck der Klasse in einem kurzen Satz.
- Beschreibung
- Ausführliche Beschreibung des Zwecks der Klasse.
- Basisklasse(n)
- Ist die Klasse von einer oder mehrerer Basisklasse abgeleitet? Wenn
ja, von welcher?
Welche Änderungen gegenüber der/den Basisklasse(n) sind
implementiert?
/**
* \class Klassenbezeichnung
* \brief Kurzbeschreibung der Klasse, endet am ersten "."
* <Leerzeile(!)>
* Ausführliche Beschreibung der Klasse
* \author Name und Email-Adresse des Authors
* \version Versionsnummer
* \date Datum
*/
class ChildClass : public ParentClass{ // Beispiel für eine
Klassendeklaration
...
}
Attribute
Alle Attribute sind unabhängig von der Sichtbarkeit in der Header-Datei
(*.h) einer Klasse zu kommentieren. Bei der Beschreibung sind besonders
zu berücksichtigen.
/**
* \brief Kurzbeschreibung des Attributs, endet mit "."
* <Leerzeile(!)>
* Evtl. umfangreichere Beschreibung, falls erforderlich
* \attention Besondere Hinweise
* \see Klasse::Methode/Attribut
*/
int counter; // Beispiel für ein Attribut
Methoden
Methoden werden in der Quelltextdatei
(*.cpp) über der Implementierung kommentiert. Steht der Kommentar an dieser
Stelle, wird die Änderung des Kommentars nicht so leicht vergessen, wenn die
Methode geändert wird, als wenn der Kommentar in der header-Datei steht.
Ein Kommentar für eine Methode umfasst
- Kurzbeschreibung
- Zweck der Methode in einem kurzen Satz.
- Beschreibung
- Ausführliche Beschreibung des Zwecks der Methode und Ergebnis im
Erfolgsfall.
- Parameter
- Auflistung aller Parameter mit einer Beschreibung des Zwecks und des
gültigen Wertebereichs.
- Rückgabewert
- Rückgabewert der Methode
- Fehlerverhalten
- Hier müssen alle Bedingungen, unter denen die Methode ein
Fehlerverhalten auslöst (Fehlermeldung/Exit oder werfen von Exceptions)
beschrieben werden. Jeder Programmierer, der die entsprechende Methode
aufruft, muß wissen, mit welchen Fehlern er zu rechnen hat und seinen Code
darauf einstellen.
/**
* \brief Kurzbeschreibung des Methode, endet mit "."
* <Leerzeile(!)>
* Ausführliche Beschreibung der Methode
* \param Name Parameter 1 Beschreibung Parameter 1
* \param Name Parameter 2 Beschreibung Parameter 2
* \exception Exceptionklasse Bedingung für die Exception
* \see Klasse::Methode/Attribut (z.B. Verweis auf dieBeschreibung in
einer Methode / einem Attribut der gleichen oder eineranderen
Klasse)
*/
void ChildClass::myMethod(int param1, int param2){ // Beispiel für eine
Methodenimplementierung
...
}
Dokumentation erzeugen
Sie erzeugen die Dokumentation in KDevelop über das Menü mit Erstellen
/ API-Dokumentation erstellen.
Hinweis:
Achten Sie auf die Warnhinweise, die während der Erzeugung der
Dokumentation ausgegeben werden und ergänzen Sie Ihre Dokumentation
entsprechend.
