doxygen - 2.pdf

(42 KB) Pobierz
Dokumentieren mit
Doxygen
Prof. Dr. Manfred Brill
Oktober 2003
Inhaltsverzeichnis
1 Doxygen
2 Dokumentation des Quelltexts
3 Konfiguration von
Doxygen
4
Doxygen
ausfuhren
¨
Literatur
1
2
3
5
5
1 Doxygen
Zur Software-Entwicklung gehort auch die Dokumentation dazu – das ist eigentlich eine Selbst-
¨
verst¨ ndlichkeit. Sie kennen das bestimmt, endlich sind alle Klassen implementiert, die Funktio-
a
nalit¨ t getestet – jetzt soll noch eine Dokumentation erstellt werden. Wenn Sie mit
Java
program-
a
miert haben kennen Sie eventuell das Werkzeug
JavaDoc.
Damit kann mit Hilfe von Kommenta-
ren, die in den Quelltexten enthalten sind eine Dokumentation erstellt werden.
Ein mit
JavaDoc
vergleichbares Werkzeug ist die Freeware
Doxygen.
Sie erstellen Ihre Softwa-
re und kommentieren dabei; je nach Ihren Angewohnheiten eventuell etwas mehr als zuvor. Sie
werden bemerken, dass die Arbeit mit
Doxygen
schnell und einfach in Ihre Implementierungsar-
¨
beit integriert werden kann.
Doxygen
unterstutzt neben
Java
die Programmiersprachen
C, C++
und
PHP.
Eine ganze Menge von großen Projekten, beispielsweise VTK oder OpenSG verwenden
Doxygen
zur Erstellung der Dokumentation.
A
Doxygen
kann neben einer HTML-Ausgabe auch L TEX,
RTF
oder
UNIX-man
-Seiten erzeugen.
Wir werden uns in diesem Text auf die
HTML
-Ausgabe konzentrieren und nur eine knappe
Einfuhrung geben. Viele Tips und Einstellungsmoglichkeiten finden Sie in [vH02].
¨
¨
Drei Schritte trennen Sie von einer Dokumentation mit
Doxygen
:
1. Sie mussen in Ihren Quelltexten entsprechende Kommentare einbauen; mehr dazu finden Sie
¨
in Abschnitt 2.
2. Sie mussen
Doxygen
konfigurieren; mehr dazu finden Sie in Abschnitt 3.
¨
¨
3. Sie mussen
Doxygen
ausfuhren; mehr dazu finden Sie in Abschnitt 4.
¨
2
Dokumentation des Quelltexts
2
2 Dokumentation des Quelltexts
Der Kern der Dokumentation mit
Doxygen
besteht darin, spezielle Kommentarblocke in Ihr Pro-
¨
gramm einzubauen. Fur jedes Element des Quellcodes gibt es fur
Doxygen
zwei
Beschreibungen:
¨
¨
eine
Kurzbeschreibung
und eine
ausfuhrliche Beschreibung.
Die Kurzbeschreibung besteht in der
¨
Regel aus einer Zeile.
Es gibt mehrere Moglichkeiten, die beiden Beschreibungen in den C++-Quelltext einzubauen. In
¨
diesem Text beschreibe ich die Variante, die ich in meinen Quelltexten verwende - und die Sie also
in dieser Form im Praktikum erhalten. Es ist Ihnen uberlassen, sich diesem Vorbild anzuschließen
¨
oder nach einem Blick in [vH02] einen eigenen Stil zu w¨ hlen.
a
Eine Kurzbeschreibung erhalten Sie durch eine Zeile der Form
//! Eine Kurzbeschreibung.
Sie konnen die Kurzbeschreibung bei der Deklaration oder der Definition stehen haben; eine
¨
gute Regel ist, die Kurzbeschreibung zur Deklaration zu schreiben. Hier ein Beispiel fur eine
¨
Kurzbeschreibung einer Klasse:
//! Virtuelle Basisklasse f¨r Standardgeometrien in OpenGL
u
class vlGeometry
{
public:
//! Defaultkonstruktor
vlGeometry(void);
Das Beispiel enth¨ lt zwei Kurzbeschreibungen: einmal fur die Klasse
vlGeometry
, einmal fur den
a
¨
¨
Defaultkonstruktor. Auf die gleiche Weise konnen Sie alle weiteren Methoden der Klasse und
¨
Datenelemente der Klasse dokumentieren. Die Beschreibungen mussen
vor
dem dokumentierten
¨
Quelltext stehen.
protected:
//! Die Parameter f¨r die Aufl¨sung der Standardgeometrien
u
o
int resU, resV;
Fur eine ausfuhrliche Beschreibung, die aus mehreren Zeilen bestehen kann, kann ein Kommen-
¨
¨
tar der Form
/*!
Eine ausf¨hrliche Beschreibung,
u
die aus mehreren Zeilen besteht. Die f¨hrenden Leerzeichen
u
in den Zeilen werden beim Erzeugen der Dokumentation ignoriert!
*/
verwendet werden. Sie sehen, eigentlich mussen Sie Ihre Kommentare nur durch das Ausru-
¨
fungszeichen erg¨ nzen – das ist doch wirklich nicht viel, oder?
a
Eine gute Regel ist, die ausfuhrliche Beschreibung zur Definition einer Klasse oder Methode zu
¨
schreiben. Sie sollten die Deklaration in eine
Header-Datei
schreiben. Enth¨ lt diese Datei auch die
a
ausfuhrlichen Beschreibungen wird dies fur die Benutzer Ihrer Programme leicht unubersichtlich
¨
¨
¨
– dafur erzeugen Sie ja die Dokumentation.
¨
Das folgende Beispiel zeigt die ausfuhrlichen Beschreibungen fur die Klasse aus dem bereits
¨
¨
gezeigten Beispiel:
#include "vlGeometry.h"
/*!
Die Basisklasse enth¨lt zwei ganze Zahlen, mit deren Hilfe die
a
abgeleiteten Klassen jeweils die Aufl¨sung festlegen k¨nnen.
o
o
F¨r das Setzen und Abfragen dieser Parameter werden entsprechende
u
inline-Funktionen definiert.
3
Konfiguration von
Doxygen
3
Dar¨berhinaus wird die rein virtuelle Funktion ::draw() deklariert,
u
die von den instanzierbaren Klassen implementiert werden muss.
*/
/*!
Die Aufl¨sungen werden jeweils mit 1 initialisiert.
o
*/
vlGeometry::vlGeometry(void)
{
resU = 1;
resV = 1;
}
Doxygen
kennt eine Menge von
Tags,
die fur die jeweiligen Text-Systeme in Links oder Index-
¨
Eintr¨ ge umgewandelt werden. Im folgenden Beispiel sehen Sie den Tag
\
param
, mit dem Sie sich
a
speziell auf Parameter einer dokumentierten Methode beziehen konnen. In
HTML
wird dadurch
¨
ein Hyperlink auf die Datei erzeugt, in der diese Parameter dokumentiert sind. Mit
\
sa
konnen
¨
Sie einen Verweis erzeugen; die Abkurzung steht fur see also“.
¨
¨
”
/*!
\param u,v sind die beiden als ganze Zahlen
deklarierten Aufl¨sungsparameter, die in den von vlGeometry
o
abgeleiteten Klassen entsprechend verwendet werden k¨nnen.
o
\sa resU \sa resV
*/
vlGeometry::vlGeometry(int u, int v)
{
resU = u;
resV = v;
}
Das Ergebnis dieser Dokumentation ist eine Menge von
HTML
-Dateien; die Einstiegsseite ist die
Datei
index.html.
Was auf dieser Einstiegsseite enthalten ist konnen Sie ebenfalls durch einen
¨
entsprechenden Kommentar festlegen. Dazu verwenden Sie den Tag
\
mainpage
und Text, den Sie
entsprechend verfassen. Hilfreich sind auch die Tags
\
author,
\
date
und
\
image
:
/*!
\mainpage
\author Manfred Brill
\date Oktober 2003
\image html vislab.jpg
Erg¨nzen Sie diesen Text und dokumentieren Sie Ihre Klassen mit
a
Hilfe von Doxygen!
F¨r die Erstellung der HTML-Seiten verwenden Sie doxywizard oder das
u
Kommando doxygen in der Cygwin-Shell. Die Konfiguration finden Sie in
der Datei doxy. In der Shell entspricht dies dann dem Kommando
<<doxygen doxy>>.
*/
3 Konfiguration von
Doxygen
Den wichtigsten Schritt haben Sie schon hinter sich – Sie haben die entsprechenden Kommentare
in Ihren Quelltext eingebaut. Bevor die Dokumentation erstellt wird mussen Sie jetzt festlegen, in
¨
3
Konfiguration von
Doxygen
4
welchem Format die Dokumentation zur Verfugung stehen soll; wo Sie abgespeichert wird und
¨
welche Bestandteile die Dokumentation enthalten sind.
Dabei konnen Sie die meisten Grundeinstellungen so belassen, wie sie von
Doxygen
als Default
¨
vorgeschlagen werden. Sie erhalten auf diese Weise beispielsweise eine komplette
Cross-Referenz
Ihres Projekts. Die Einstellung fur
Doxygen
stehen in einer Konfigurationsdatei. Das Format
¨
entspricht einem
Makefile.
In einer Shell, sei es
cmd.exe
in
MS Windows
oder eine
UNIX
-Shell
konnen Sie mit
¨
doxygen -g <config-file>
eine entsprechende Datei erzeugen. Geben Sie keinen Namen an und nur die Option
-g
, dann
wird eine Datei mit dem Namen
Doxy-file
erzeugt.
Wollen Sie anschließend die Einstellungen uberprufen oder ver¨ ndern, dann konnen Sie dies mit
¨
¨
a
¨
Hilfe eines ASCII-Editors durchfuhren. Eine Alternative dazu ist das Werkzeug
doxywizard
, das
¨
ein kleines Frontend zum Erzeugen, Ver¨ ndern und auch Speichern von Konfigurationsdateien
a
unter
Microsoft Windows
anbietet. In Abbildung 1 sehen Sie eine Darstellung des Wizards.
Abbildung 1:
Der
doxywizard
in Aktion
Zwei Eintr¨ ge sind wichtig. Einmal mussen Sie das Verzeichnis angeben, in dem die Ausgabe
a
¨
erfolgen soll.
Doxygen
legt
HTML
-Ausgaben in einem Unterverzeichnis mit dem Namen
html,
A
¨
¨
L TEX-Ausgaben im Unterverzeichnis
latex
ab. Und Sie mussen naturlich festlegen, wo die Ein-
gaben, also die zu dokumentierenden Quelltexte liegen. Dies konnen Sie unter dem Reiter
INPUT
¨
durchfuhrn. Fur kleine Projekte reicht es, die Konfigurationsdatei in das Verzeichnis zu spei-
¨
¨
chern, in dem sich die zu bearbeitenden Quellen befinden. Bei großen Projekten, die vielleicht
sogar einen ganzen Baum von Unterverzeichnissen mit Quellen enthalten, geben Sie als
INPUT
die Wurzel des Baums an. Sie konnen auch Muster wie
*.cpp
und
*.h
angeben, um sicher zu stel-
¨
Literatur
5
len, dass die richtigen Quelldateien bearbeitet werden. Und Sie mussen den
RECURSIVE
-Tag auf
¨
YES
stellen!
Sollen die Quellen in der Dokumentation enthalten sein, dann stellen Sie den Wert fur
INLI-
¨
NE SOURCES
auf
YES
; setzen Sie
SOURCE BROWSER
auf
YES
, falls Sie eine
Cross-Referenz
Ihrer
Quellen erzeugen mochten.
¨
4
Doxygen
ausfuhren
¨
Dies wird jetzt der einfachste Schritt. In einer Shell geben Sie
doxygen <config-file>
ein. Damit wird, je nach Konfigurationseinstellung, die gewunschte Ausgabe erzeugt. Haben Sie
¨
kein Ausgabeverzeichnis mit dem Tag
OUTPUT DIRECTORY
festgelegt dann wird die Ausgabe
im aktuellen Verzeichnis abgelegt.
Tip:
Sie konnen die Erzeugung der Dokumentation in Ihren Makefile integrieren. Damit
¨
¨
wird es moglich,
Doxygen
in
Eclipse
anzustoßen. Alles was Sie dazu benotigen ist
¨
ein entsprechendes
make-Target
.
Angenommen, die Konfigurationsdatei hat den Namen
doxy,
dann reicht ein Target
doc und die Regel
doxygen doxy
. Mehr zur Arbeit mit Makefiles finden Sie in [Bri03].
Fur die Ansicht der
HTML
-Ausgabe mussen Sie einen Browser verwenden, der
CSS
unterstutzt.
¨
¨
¨
A
T X-Ausgabe muss anschließend naturlich bearbeitet werden. Dies konnen Sie wie gewohnt
Die L E
¨
¨
durchfuhren; die Hauptdatei tr¨ gt als Default den Namen
refman.tex.
Oder, falls Sie
make
in-
¨
a
A
stalliert haben, mit der Eingabe von
make
in dem Verzeichnis, in dem
Doxygen
die L TEX-Ausgabe
abgelegt hat. Dadurch wird eine Datei
refman.dvi
erzeugt. Wollen Sie eine Postscript-Datei,
¨
dann geben Sie
make ps
ein; vorausgesetzt Sie haben das Programm
dvips
installiert. Sie konnen
mit dem Makefile auch
PDF
erzeugen, vorausgesetzt Sie haben
ghostscript
installiert. Geben Sie
einfach
make pdf
ein. Ist in der Konfiguration der Tag
PDF HYPERLINKS
auf
YES
gesetzt, dann
werden in der
PDF
-Datei Links erzeugt!
Literatur
[Bri03] B
RILL
, M
ANFRED
:
Programmieren mit
Cygwin
und
UNIX.
Fachhochschule Kaiserslautern,
2003.
[vH02] H
EESCH
, D
IMITRI VAN
:
User Manual for Doxygen 1.2.17,
2002.

Plik z chomika:

Inne pliki z tego folderu:

Inne foldery tego chomika:

Zgłoś jeśli naruszono regulamin