Doxygen How-To

Fragen, Anregungen oder Vorschlge an Jochen.

Prinzipielles zur Dokumentation

Prinzipiell sollte man in erster Linie dokumentieren, warum etwas gemacht wird und welche
Auswirkungen es hat. Das Wie und Was erkennt man nmlich meistens schon am Code selbst. Nur
manchmal ist es ntig zu dokumentieren, was ein gewisses Stck Code tut, vor allem, wenn man
sehr kryptischen Code verwendet (Bit twiddling hacks oder hnliches) oder bei Inline-Assembler.

Grundlegendes zu Doxygen
Doxygen Dokumentationen werden im Code-Kommentar geschrieben und befinden sich vor dem zu
dokumentierenden Objekt. Damit Doxygen wei, dass der Kommentar zur Dokumentation gehrt
muss man den Kommentar mit einem Ausrufezeichen beginnen: /*! */
Doxygen Befehle knnen auf zwei Arten geschrieben werden: Entweder \command oder
@command. Manche Doxygen Befehle beziehen sich nur auf das nchste Wort (z.B. \a, \p), manche
auf die folgende Zeile (z.B. \param, \sa) und manche auf den folgenden Absatz (z.B. \brief, \note).
Bei den Befehlen, die sich auf einen Absatz beziehen muss man eine Leerzeile am Ende einfgen
und den Absatz zu beenden.
Zum Erstellen der Dokumentation lsst man doxygen mit einem doxyfile laufen
(Konfigurationsdatei). Mit Eclox (Eclipse Plugin fr Doxygen) geht das einfach ber den Button
Build Doxyfile (Symbol ist ein blaues @). Nur noch doxyfile auswhlen und OK klicken.

Wichtige Doxygen Befehle

Befehl
\a
\e
\brief
\class class [headername][headerfile]

\code \endcode
\exception object description

\n
\note
\warning
\attention
\p
\param[[in]|[out]] parameter description

Bedeutung
Kursiv, Hervorhebung von Argumenten/Variablen im
Text
Kursiv, sonstige Hervorhebung
Kurzbeschreibung einer Klasse/Methode/etc.
Dokumentation der Klasse class; wird nur bentigt um
in der Dokumentation den Header mit
Anfhrungszeichen und nicht mit spitzen Klammern
anzuzeigen (lsst sich leider nicht global festlegen)
Beispiel Quellcode Umgebung
Beschreibung mglicher Fehler; object ist das
geworfene Object und description die entsprechende
Beschreibung
Zeilenumbruch
Schreibt Note: bzw. Warning: bzw. Attention: als
berschrift und der nachfolgende Text wird eingerckt
Typewriter, Hervorhebung von Parametern im Text
Parameterbeschreibung bei einer Funktion; parameter
ist der zu beschreibende Parameter und description die
entsprechende Beschreibung; [in] bzw. [out] geben an,
ob es sich um einen reinen Eingabe- oder

\ref anchor [link-text]

\return description
\sa
\section section title
\subsection subsection title
\subsubsection subsubsection title
\paragraph paragraph title

Ausgabeparameter handelt (optional)

Link zu Anker/Seite/Beispiel etc.; anchor ist der
Bezeichner auf den der Link zeigen soll und link-text ist
der angezeigte Text (optional)
Beschreibung fr den Rckgabewert
Schreibt See also; Einleitung fr eine Link-Liste
Elemente zur Textgliederung; section, subsection,
subsubsection und paragraph sind die Bezeichner und
title die angezeigten Titel/berschriften; knnen mit \ref
verlinkt werden

Dokumentationsbeispiel
/*! \class myClass myClassHeader.h include/myClassHeader.h
* \brief My own class.
*
* I created it and I like it. Its very useful and handy.
* myClass does what I want.
*
* Example:
* \code
* myClass myClassInstance();
* myClassInstance.doWhatIWant();
* \endcode
*
* \sa notMyClass, anotherClass::someMethod()
*/
class myClass
{
public:
//####### Enums #######
/*! \brief My own enum.
*
* Some nice enumerators.
*/
enum MyEnum {
someEnum,
//!< The first enum.
someMoreEnum
//!< Another enum.
};
//####### Constructors #######
/*! \brief Standard-Constructor.
*
* Does nothing special.
*/
myClass() { };
/*! \brief Copy-Constructor.
*
* Creates a deep copy of \p other.
*
* \param[in] other The instance of myClass to be copied.

*/
myClass(const myClass& other) { _member = other._member; };
//####### Destructor #######
/*! \brief Standard-Destructor.
*
* Does nothing special.
*/
~myClass() { };
//####### Public Methods #######
/*! \brief This method does what I want.
*
* This is another inline-method.
*
* \sa doNotWhatIWant()
*/
void doWhatIWant() { ++_member; };
int doNotWhatIWant();
private:
//####### Private Members #######
int _member;
};
/*! \brief This method does not what I want.
*
* This is not an inline-method.
*
* \section list_example Example of a List
* Here is a list:
* - this is the first list element
* - this is another list element
*
- and this is subelement
*
- and another subelement
*
- we can go even deeper
*
.
*
The point above allows us to continue with the second
*
subelement.
* - and here the list continues
*
* \section numbered_list_examples Example of a numbered List
* Now follows a numbered list:
* <OL>
*
<LI>this is the first point</LI>
*
<LI>this is the second point</LI>
* </OL>
*
* \return What you have done.
*

* \sa doWhatIWant()
*/
int myClass::doNotWhatIWant()
{
--_member;
return _member;
}