Dokumentationskommentare in C++
Jede definierte Entität sollte auch dokumentiert werden. In dieser Lektion werden die Grundlage der Dokumentation im Doxygen -Format beschrieben. Diese Form der Dokumentation kann so auch verwendet werden, wenn das Programm Doxygen nicht zur Verfügung steht. Doxygen erlaubt es, aus einer mit Dokumentation angereicherten Datei automatisch Dokumentationsdateien zu erstellen.
Solche Kommentare werden auch als Dokumentationskommentare (documentation comments, doc comments) bezeichnet. Alle anderen Kommentare kann man auch als Implementationskommentare (implementation comments) ansehen, da sie sich mit Aspekten der Implementation beschäftigen sollten. Diese Unterscheidung und die Festlegung zur Schreibweise von Dokumentationskommentaren wird allerdings nicht durch die Programmiersprache C++ festgelegt, sondern stellt eine zusätzliche Empfehlung dar.
Kurzbeschreibungen
Direkt vor eine Definition kann ein einzeiliger Kommentar geschrieben werden, der die definierte Entität kurz beschreibt. Wird ein einzeiliger Kommentar mit drei Schrägstrichen "///" eingeleitet, ist er für Doxygen als Dokumentationskommentar gekennzeichnet.
Normalerweise wird ein Dokumentationskommentar direkt vor das zu Dokumentierende geschrieben. So finden sich in dem Beispielprogramm "kuckuck3d.cpp" Dokumentationskommentare vor jeder Funktionsdefinition.
kuckuck3d.cpp#include <iostream>
#include <ostream>
/// Refrain des Liedes "Auf einem Baum ein Kuckuck sass" ausgeben
static void refrain()
{ ::std::cout << "Sim sa la dim, bam ba,\n";
::std::cout << "Sa la du, sa la dim -\n"; }
/// Das Lied "Auf einem Baum ein Kuckuck sass" ausgeben
int main()
{ // Kann man das nicht noch verkuerzen?
{ ::std::cout << "Auf einem Baum ein Kuckuck, -\n"; refrain();
::std::cout << "Auf einem Baum ein Kuckuck sass.\n"; }
{ ::std::cout << "Da kam ein junger Jaeger, -\n"; refrain();
::std::cout << "Da kam ein junger Jaegersmann.\n"; }
{ ::std::cout << "Der schoss den armen Kuckuck, -\n"; refrain();
::std::cout << "Der schoss den armen Kuckuck tot.\n"; }}
Das Werkzeug Doxygen erlaubt es, Dokumentationsdateien automatisch aus einer wie beschrieben mit Dokumentationskommentaren angereicherten Quelldatei zu erzeugen. Dieses Werkzeug kann für einige verbreitete Betriebssysteme durch Datenfernübertragung leicht beschafft und installiert werden und darf in gewissem Rahmen kostenlos verwendet werden. Doxygen bietet noch mehr Möglichkeiten als hier beschrieben werden—In dieser Lektion werden nur einfache Beispiele der Verwendung vorgestellt.
Doxygen benötigt eine Konfigurationsdatei "Doxyfile", in der die Einstellungen gespeichert werden. Diese kann mit der Option "-g" (im Projektverzeichnis mit der Quelldatei) erzeugt werden.
Konsole [Ausschnitt, gekuerzt]doxygen -g
Configuration file `Doxyfile' created.
Now edit the configuration file and enter
doxygen Doxyfile
to generate the documentation for your project
In der Konfigurationsdatei muß die Option "EXTRACT_ALL", die festlegt, daß alle in Frage kommenden Bestandteile des Quelltextes dokumentiert werden sollen, auf den Wert "YES" gesetzt werden. Die Sprache der Ausgabe kann als Deutsch ("German") festgelegt werden.
Doxyfile [Ausschnitte, alter Zustand]EXTRACT_ALL = NO
OUTPUT_LANGUAGE = EnglishDoxyfile [Ausschnitt, neuer Zustand]EXTRACT_ALL = YES
OUTPUT_LANGUAGE = German
Falls sich im Verzeichnis nur die zu dokumentierende Datei befindet, dann kann Doxygen nun ohne weitere Einstellungen oder Argumente aufgerufen werden. Es sucht dann nach Quelldateien.
Konsole [Ausschnitt, gekuerzt]doxygen
Searching for include files...
Reading input files...
Preprocessing kuckuck3d.cpp...
Parsing file kuckuck3d.cpp...
Generating index page...
Generating file documentation...
Generating style sheet...
Doxygen erzeugt unter anderem eine HTML -Datei "kuckuck3d_8cpp.html" mit der gewünschten Dokumentation.
kuckuck3d.cpp-Dateireferenz [Dokumentation, Ausschnitt, gekuerzt]Funktionen
int main ()
Das Lied "Auf einem Baum ein Kuckuck sass" ausgeben.
Dokumentation der Funktionen
int main ()
Das Lied "Auf einem Baum ein Kuckuck sass" ausgeben
Erzeugt am Thu Dec 26 03:18:05 2002 von doxygen 1.3
Man beachte, daß die Dokumentation keine Beschreibung der Methode "refrain" enthält, obwohl ihr ein Dokumentationskommentar direkt vorangestellt wurde. Das liegt daran, daß diese Methode nicht öffentlich ist (sie wurde mit dem Schlüsselwort "static" definiert) und daher nicht zur Schnittstelle, also zu den nach außen sichtbaren (von außen aufrufbaren) Funktionen, der Quelldatei gehört. Da diese Entität nicht von außerhalb der Datei verwendet werden kann, braucht ihre Bedeutung auch nicht in der Dokumentation beschrieben zu werden.
Auch der Kommentar "// Kann man das nicht noch verkuerzen?" wird nicht in die Dokumentation aufgenommen, weil er nicht als Dokumentationskommentar gekennzeichnet ist. Dieser Kommentar betrifft ja auch nicht die Schnittstelle der Funktion, sondern ihre Implementation.
Detaillierte Beschreibung
Ein Dokumentationskommentar kann auch mit "/**" eingeleitet werden, wie in dem Programm "kuckuck3d1.cpp". Solch ein Dokumentationskommentar gilt dann als detaillierte Beschreibung der Entität.
Es ist auch möglich. innerhalb eines mehrzeiligen Kommentars die Kurzbeschreibung mit dem Kommando "\brief" einzuleiten, die dann mit einer Leerzeile beendet werden muß, auf die der detaillierte Kommentar folgen kann.
Wenn ein Kommentar sich auf die ganze Datei beziehen soll, so muß dieser mit dem Kommando "\file" und dem Dateinamen eingeleitet werden.
Das Programmbeispiel "kuckuck3d1.cpp" zeigt Beispiele der zuletzt beschriebenen Möglichkeiten.
kuckuck3d1.cpp/** \file kuckuck3d1.cpp
\brief Refrain des Liedes "Auf einem Baum ein Kuckuck sass" ausgeben.
Dieses Programm gibt die ersten drei Strophen des Liedes
"Auf einem Baum ein Kuckuck sass" aus. */
#include <iostream>
#include <ostream>
/// \brief Refrain des Liedes "Auf einem Baum ein Kuckuck sass" ausgeben.
///
/// Diese Funktion gibt den gesamten Refrain des
/// bekannten Liedes "Auf einem Baum ein Kuckuck sass" aus.
static void refrain()
{ ::std::cout << "Sim sa la dim, bam ba,\n";
::std::cout << "Sa la du, sa la dim -\n"; }
/// Das Lied "Auf einem Baum ein Kuckuck sass" ausgeben.
/** Diese Funktion gibt die ersten drei Strophen des Liedes
"Auf einem Baum ein Kuckuck sass" aus. */
int main()
{ { ::std::cout << "Auf einem Baum ein Kuckuck, -\n"; refrain();
::std::cout << "Auf einem Baum ein Kuckuck sass.\n"; }
{ ::std::cout << "Da kam ein junger Jaeger, -\n"; refrain();
::std::cout << "Da kam ein junger Jaegersmann.\n"; }
{ ::std::cout << "Der schoss den armen Kuckuck, -\n"; refrain();
::std::cout << "Der schoss den armen Kuckuck tot.\n"; }}kuckuck3d1.cpp-Dateireferenz [Doxygen-Ausgabe, gekuerzt]Refrain des Liedes "Auf einem Baum ein Kuckuck sass" ausgeben.
Funktionen
int main ()
Das Lied "Auf einem Baum ein Kuckuck sass" ausgeben.
Ausfuehrliche Beschreibung
Refrain des Liedes "Auf einem Baum ein Kuckuck sass" ausgeben.
Dieses Programm gibt die ersten drei Strophen des Liedes "Auf einem
Baum ein Kuckuck sass" aus.
Dokumentation der Funktionen
int main()
Das Lied "Auf einem Baum ein Kuckuck sass" ausgeben.
Diese Funktion gibt die ersten drei Strophen des Liedes "Auf einem
Baum ein Kuckuck sass" aus.
Erzeugt am Thu Dec 26 03:12:22 2002 von doxygen 1.3
Dokumentation von Wertfunktionen
Mit der ersten mit "@" anfangenden Zeile eines Dokumentationskommentars wird die allgemeine Beschreibung der folgenden Entität beendet. Die Markierung "@return" kennzeichnet die Beschreibung des Ergebnisses einer Funktion.
Dokumentation [Ausschnitt]wochentage
private int wochentage()
Ergibt Zahl der Wochentage.
Returns:
Zahl der Wochentageresult.cpp#include <iostream>
#include <ostream>
/// Ergibt Zahl der Wochentage.
/**
* @return Zahl der Wochentage
*/
int wochentage(){ return 7; }
int main(){ ::std::cout << 2 * wochentage() << '\n'; }::std::cout14