Doxygen How-To Fragen, Anregungen oder Vorschläge 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 nämlich meistens schon am Code selbst. Nur manchmal ist es nötig zu dokumentieren, was ein gewisses Stück 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 gehört muss man den Kommentar mit einem Ausrufezeichen beginnen: /*! … */ Doxygen Befehle können auf zwei Arten geschrieben werden: Entweder \command oder @command. Manche Doxygen Befehle beziehen sich nur auf das nächste 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 einfügen und den Absatz zu beenden. Zum Erstellen der Dokumentation lässt man doxygen mit einem doxyfile laufen (Konfigurationsdatei). Mit Eclox (Eclipse Plugin für Doxygen) geht das einfach über den Button „Build Doxyfile“ (Symbol ist ein blaues @). Nur noch doxyfile auswählen und „OK“ klicken.

Wichtige Doxygen Befehle Befehl Bedeutung \a Kursiv, Hervorhebung von Argumenten/Variablen im

Text \e Kursiv, sonstige Hervorhebung \brief Kurzbeschreibung einer Klasse/Methode/etc. \class class [headername][“headerfile”] Dokumentation der Klasse class; wird nur benötigt um

in der Dokumentation den Header mit Anführungszeichen und nicht mit spitzen Klammern anzuzeigen (lässt sich leider nicht global festlegen)

\code … \endcode Beispiel Quellcode Umgebung \exception object description Beschreibung möglicher Fehler; object ist das

geworfene Object und description die entsprechende Beschreibung

\n Zeilenumbruch \note \warning \attention

Schreibt „Note:“ bzw. „Warning:“ bzw. „Attention:“ als Überschrift und der nachfolgende Text wird eingerückt

\p Typewriter, Hervorhebung von Parametern im Text \param[[in]|[out]] parameter description 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

Ausgabeparameter handelt (optional) \ref anchor [“link-text”] Link zu Anker/Seite/Beispiel etc.; anchor ist der

Bezeichner auf den der Link zeigen soll und link-text ist der angezeigte Text (optional)

\return description Beschreibung für den Rückgabewert \sa Schreibt “See also”; Einleitung für eine Link-Liste \section section title \subsection subsection title \subsubsection subsubsection title \paragraph paragraph title

Elemente zur Textgliederung; section, subsection, subsubsection und paragraph sind die Bezeichner und title die angezeigten Titel/Überschriften; können mit \ref verlinkt werden

Dokumentationsbeispiel /*! \class myClass myClassHeader.h “include/myClassHeader.h” * \brief My own class. * * I created it and I like it. It’s 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; }