Objektorientierte und generische Programmierung

Objektorientierte und generische Programmierung Institut für Wirtschaftsinformatik Dokumentieren von Quelltexten mit Doxygen Ulrich W. Eisenecker 19. März 2011

Übersicht Grundlagen Warum dokumentieren? Warum automatisiert? Doxygen Bezugsquelle, Installation Eingabe- und Ausgabeformate, Graphen und Diagramme, Befehle Dokumentationskommentare, Beispiele Aufruf per Kommandozeile, Aufruf per doxywizard Anregungen zum Selbststudium Schlussbemerkungen Quellen 2

Warum dokumentieren? Sinn und Zweck des eigenen Quellcodes auch nach einem halben Jahr noch verstehen können Anderen Beteiligten, zum Beispiel Entwickler und Qualitätssicherer, das Verständnis des eigenen Quellcodes erleichtern, etwa bei APIs Implementierungsentscheidungen begründen und nachvollziehbar machen (Rückverfolgbarkeit, engl. traceability) Wartbarkeit verbessern und somit unnötige Kosten vermeiden 3

Warum automatisiert dokumentieren? Konsistenz von Dokumentation und Quelltext sicherstellen Möglichkeit der automatischen Formatierung und Erzeugung von Querverweisen Manuell müssten diese mit hohem Aufwand gepflegt werden Quelltextkommentare beinhalten wichtige Meta-Informationen Ein Dokumentationssystems kann diese automatisiert in eine formale Darstellung überführen Eine vorgegebene Syntax sorgt für eine einheitliche Dokumentation Dokumentation kann vom System automatisch erzeugt werden, etwa jede Nacht Integration mit Build-Systemen möglich 4

Bezugsquelle Download über die Home Page: http://www.doxygen.org Als Quelltext Als Binärdistribution für Linux, Windows, Mac OS X, Solaris 9 Als Bestandteil der Cygwin-Umgebung: http://www.cygwin.com/ Im Weiteren wird nur auf die Benutzung der Binärdistribution für Windows eingegangen Diese ermöglicht eine komfortable und einfache Installation 6

Installation Download der Binärdistribution für Windows Es wird die Verwendung des Setup-Programms empfohlen, da es alle erforderlichen Kompenenten enthält Ausführen von doxygen-<version>-setup.exe Installation im Modus Full Installation durchführen Insbesondere die Komponente doxywizard GUI sollte installiert werden Es handelt sich hierbei um eine komfortable Oberfläche zur Erzeugung der Konfigurationsdatei für Doxygen 7

Eingabeformate Unterstützung unter anderem für C/C++ Java IDL (CORBA und Microsoft) C# Es lassen sich Dateien, Namensräume, Klassen, structs, unions, Templates, Variablen, Funktionen, typedefs, enums und defines dokumentieren 8

Ausgabeformate Doxygen kann folgende Ausgabeformate direkt erzeugen HTML XML LaTeX Man pages RTF Qt Help Project Folgende Formate werden indirekt unterstützt Compressed HTML (über Microsoft HTML Help Workshop) PostScript (aus LaTeX-Ausgabe) PDF (aus LaTeX-Ausgabe) Qt Compressed Help 9

Graphen und Diagramme Doxygen ermöglicht die grafische Aufbereitung folgender Informationen Vererbungsdiagramme für C++-Klassen GRAPHICAL_HIERARCHY: Klassenhierarchie (nur HTML) CLASS_GRAPH: Direkte und indirekte Vererbungsbeziehungen INCLUDE_GRAPH: Visualisierung der include Abhängigkeiten (HTML und RTF) COLLABORATION_GRAPH: Vererbungsbeziehungen mit Basisklassen und Verwendungsbeziehungen mit anderen structs und Klassen CALL_GRAPH: Anzeige der direkten und indirekten Funktionsaufrufe aus einer Funktion heraus 10

Beispiel CLASS_GRAPH 11

Beispiel INCLUDE_GRAPH 12

Beispiel - COLLABORATION_GRAPH 13

Beispiel - CALL_GRAPH 14

Befehle Innerhalb eines Dokumentationskommentars können zwei Arten von Befehlen eingesetzt werden Spezialbefehle Sie werden mit \ oder @ eingeleitet und können Parameter erhalten Sie dienen der Kennzeichnung bestimmter Dokumentationsbereiche, der Gruppierung, der Beeinflussung der Ausgabe etc. HTML-Befehle Ein Dokumentationskommentar kann bestimmte HTML-Elemente beinhalten Diese werden in der HTML-Ausgabe übernommen und bei anderen Ausgabeformaten in entsprechende Äquivalente umgesetzt Eine Liste aller Befehle mit Erklärungen ist dem Doxygen-Handbuch zu entnehmen (Bereiche Special Commands, HTML Commands) 15

Dokumentationskommentare (1) Doxygen bietet viele Möglichkeiten, einen Bereich als Dokumentation auszuzeichnen; diese lehnen sich an die bekannten Kommentare aus C++ und Java an Für ein zu dokumentierendes Code-Fragment können zwei Arten von Beschreibungen hinterlegt werden Kurze und detaillierte Beschreibung Jede der beiden Arten ist optional, darf jedoch höchstens einmal vorkommen Im Folgenden wird auf zwei Möglichkeiten der Auszeichnung eingegangen Weitere Möglichkeiten sind dem Handbuch zu entnehmen 16

Dokumentationskommentare (2) Qt-Style /*! \brief Kurze Beschreibung. * Kurze Beschreibung fortgesetzt. * * Detaillierte Beschreibung beginnt hier. */ Der Kommentar beginnt wie ein normaler C-Kommentar gefolgt von einem Ausrufezeichen: /*! Die kurze Beschreibung wird mit dem Spezialbefehl \brief eingeleitet Der nach einer Leerzeile folgende Text wird automatisch als detaillierte Beschreibung angesehen 17

Dokumentationskommentare (3) JavaDoc-Style mit JAVADOC_AUTOBRIEF = YES /** Kurze Beschreibung, die an diesem Punkt endet. * Detaillierte * Beschreibung beginnt hier. */ Kommentar beginnt wie ein normaler C-Kommentar gefolgt von einem Stern: /** Ist die Option JAVADOC_AUTOBRIEF auf YES gesetzt, bildet der erste Satz des Kommentars die kurze Beschreibung Nachfolgend kommt die detaillierte Beschreibung 18

Beispiel Dokumentation einer Methode /*! Method for calculating the area. \param a the length \param b the height \return Area is returned */ int calcarea(int a, int b); Im Beispiel fehlt eine kurze Beschreibung, es ist nur eine detaillierte vorhanden Die Parameter a und b sind mit dem Spezialbefehl \param kommentiert Der Rückgabewert ist mit dem Spezialbefehl \return kommentiert 19

Beispiel Makrodokumentation für #define /*! \def c_water Specific heat capacity of water. */ #define c_water 4.19 Der Spezial-Befehl \def mit dem Parameter <variable_name> gibt an, dass <variable_name> ein #define-wert ist Der Kommentar steht direkt oberhalb von #define 20

Aufruf per Kommandozeile Doxygen benötigt eine Konfigurationsdatei Diese enthält alle projektbezogenen Einstellungen doxygen -g <config-file> erzeugt eine Vorlagendatei Diese muss den eigenen Wünschen angepasst werden doxygen <config-file> startet die Generierung der Dokumentation anhand der Einstellungen in der übergebenen Konfigurationsdatei Eine komfortable Variante zur Konfiguration und für den Aufruf stellt das Doxygen-GUI-Frontend, doxywizard genannt, dar Dieses wird im Folgenden vorgestellt 21

Aufruf per doxywizard (1) Die einfachste Methode zum Einstieg ist der Wizard-Modus Er führt durch alle nötigen Konfigurationsschritte 22

Aufruf per doxywizard (2) Projektinformationen festlegen Quellverzeichnis auswählen Rekursive Verarbeitung aktivieren Zielverzeichnis auswählen 23

Aufruf per doxywizard (3) Alle Fragmente oder nur dokumentierte in die Dokumentation übernehmen? Quelltext in die Dokumentation einbinden? Einstellungen für die Optimierung der Dokumentationsergebnisse 24

Aufruf per doxywizard (4) Festlegung der Ausgabeformate HTML mit Frames und Navigationsbaum sowie LaTeX für verlinktes PDF sind gut nutzbare Ausgabeformate 25

Aufruf per doxywizard (5) Festlegung der zu erzeugenden Diagramme In der Windows-Version ist das dot tool enthalten Somit können auch die hier deaktivierten Diagramme erzeugt werden, ohne zusätzliche Software zu installieren 26

Aufruf per doxywizard (6) Speichern der im Hintergrund per Wizard erzeugten Konfigurationsdatei Damit kann die Erzeugung der Dokumentation schnell und problemlos erneut angestoßen werden 27

Aufruf per doxywizard (8) Verzeichnis festlegen, in dem Doxygen gestartet wird (üblicherweise das Wurzelverzeichnis der Quelltexte) Run doxygen startet die Generierung der Dokumentation 28

Anregungen zum Selbststudium Informieren Sie sich im Handbuch über weitere Möglichkeiten zur Erzeugung von Dokumentationskommentaren Nehmen Sie eines Ihrer bisherigen C++-Projekte (möglichst mit mehreren Dateien und Klassen mit Vererbungsbeziehungen) und dokumentieren Sie es Erzeugen Sie eine Doxygen-Konfigurationsdatei per doxywizard Lassen Sie alle möglichen Diagramme erzeugen Schauen Sie sich dabei auch den Expertenmodus an Erzeugen Sie mit Hilfe der Konfigurationsdatei eine Dokumentation für Ihr Projekt 30

Schlussbemerkungen Zweck dieser Präsentation ist es, einen ersten Eindruck von der Mächtigkeit des Doxygen-Werkzeugs zu vermitteln und einen Einstieg zu ermöglichen Es wurden bei weitem nicht alle Möglichkeiten von Doxygen behandelt Insbesondere wurde auf die Darstellung komplexer Projekte mit externer Dokumentation, Gruppierung und Preprocessing verzichtet, da dies den Rahmen sprengen würde All diese Themen werden ausführlich und mit Beispielen im Doxygen-Handbuch erklärt 32

Quellen Doxygen-Handbuch: http://www.doxygen.org/manual.html Manfred Brill: Dokumentieren mit Doxygen, 2003, http://www.vislab.de/cgbuch/intros/doxygen.pdf 34