Wer unter Windows, Linux oder MacOS in C / C++ / Java o.ä. programmiert und ne coole Lösung sucht, schnell Dokus zu generieren, ohne viel zu tippeln: Doxygen!
Wie funzt dat?
- Doxygen ist ein Parser und sucht u.a. nach JavaDoc-Tags
- aus den Tags wird eine komplette Doku als HTML, PDF, RTF usw. gebaut
- spezielle Tags erlauben sogar Unterseiten, Verlinkungen usw.
- es werden auch Graphische Abhängigkeiten (Diagramme) erzeug
Wat kost?
Nischt – ist OpenSource 😉 …nur a bissle Tipparbeit.
Wo herkriegen?
www.doxygen.org – hier gibbets auch deutsche Anleitungen etc.
Ein hübsches Beispiel gibbets hier.
Schnelleinstieg
Im folgenden Beispiel ist mal eine Klassendoku für C++ zu sehen – die gleichen Tags (Kommentare) können 1:1 für Java verwendet werden:
/**
* @brief Klasse zum Messen von Fuellstaenden.
*
* @warning Es erfolgt direkter Zugriff auf die SPS!
*
* Diese Klasse besitzt Schnittstellen zur SPS S5 und
* kann mittels Methode getFillValue() den aktuellen
* Fuellstand auslesen und mittels reset() SPS neustarten.
*/
class FillState
{
public:
double getFillValue(); ///< SPS auslesen
void reset(); ///< startet SPS neu
};
/// startet die SPS neu
void FillState::reset() {
SPS::restart(0,0,"db1");
}
Die Syntax / Doxygen Tags
Tags fuer Beschreibungsbloecke/-Zeilen:
/** Beschreibungsblock, idealer Weise in Zeile ueber * der Deklaration des zu dokumentierenden Elementes */ /// ... Kurzbeschreibung in Zeile ueber Deklaration . von Funktion/Methode/Variable/Klasse ///< ... Kurzbeschreibung hinter der Deklaration
Tags innerhalb von Beschreibungsblock:
@author Name des/der Autor(en) @brief Zeile fuer Kurzbeschreibung @bugs Liste der Bugs (sollte selten auftauchen) @class leitet Beschreibung fuer Klasse ein @code leitet Absatz mit Sourcecode ein @date Absatz fuer Datum @endcode schliesst Absatz mir Sourcecode ab @exception Beschreibung der Exception @file Beschreibungsblock fuer aktuelle Datei @fn Beschreibung fuer Funktion/Methode @returns Beschreibung des Rueckgabewertes @retval Beschreibung des Rueckgabewertes @version Absatz fuer Versions-Informationen @warning Absatz fuer Warnungen
Tags fuer die Textgestaltung: (ebenfalls in Beschreibungsbloecken)
@arg Listeneintrag/Gliederung (Aufzaehlungszeichen) @c folgendes Wort erscheint in Schriftart fester . Breite, z.B. in "Courier" @page leitet Beschreibungsblock fuer Seite mit . Titel ein und als Ziel fuer Links @par Leitet Absatz mit Namenein, somit kann . als Ziel fuer Links verwendet werden @par dito, aber mit Ueberschrift, welche hervorgehoben . dargestellt wird (bold) @mainpage leitet Beschreibungsblock fuer Hauptseite der . Doku ein - befindet sich in *.dox-Dateien @ref erzeugt Link auf Ziel (muss ein Doxygen-Ziel . sein, z.B. Name eines Absatzes/einer Sektion) @section [s] Absatz mit Thema namens [s] und Ueberschrift @subsection [s] Unterthema namens [s] und Ueberschrift, . [s] kann als Ziel fuer Links genutzt werden
Ein Artikel zu Dokus und Quelltextdokus folgt noch.
Schnelleinstig: Sourcedokus mit Doxygen