Das bedeutet, das Tool liest alle Dateien eines Code-Projekts. Es speichert alle Klassen und Methoden sowie die dazugehörigen Kommentare und generiert daraus ein Klassenverzeichnis, welches der Benutzer anschliessend anschauen kann.
Dieses Tool kann verschiedenste Sprachen lesen sowie die Dokumentation in verschiedenen Formaten ausgeben.
Ich werde als Programmiersprache wie meistens C# verwenden, das Ausgabeformat ist HTML.
So wird Doxygen benutzt
Das Tool kann man hier gratis downloaden.Nach der Installation findet man unter "Alle Programme/doxygen" das Tool "Doxywizard", welches einem beim Erstellen der Konfiguration hilft.
Das GUI ist ziemlich selbsterklärend, jedoch gibt es sehr viele Konfigurationsmöglichkeiten.
Hier das Wichtigste:
Im Tab "Wizard" und dem Knoten "Project" muss das korrekte "Source code directory", also der Projektordner, sowie das "Destination directory", also der Ausgabeordner angegeben werden.
Ausserdem sollte das Häkchen "Scan recursively" gesetzt werden, damit alle Unterordner des ausgewählten Projektordners durchsucht werden.
Dem Projekt den korrekten Namen und die richtige Versionsnummer zu geben ist natürlich auch sinnvoll.
Im Knoten "Mode" empfehle ich noch unter "Select the desired extraction mode:" "All Entities" auszuwählen, damit auch wirklich alles vorhanden ist. Ausserdem kann noch die Optimierung für die genutzte Sprache auswählen.
Im Knoten "Output" kann noch an der Ausgabe-Datei herum geschraubt werden.
Hier kann z.B. das Farbschema geändert, eine Navigation sowie ein Suchfeld hinzufügen werden usw.
Im Tab "Expert" kann alles Mögliche eingestellt werden. Die Sprache der ausgegeben Datei kann man unter "OUTPUT_LANGUAGE" anpassen, was womöglich gewünscht ist.
Im Tab "Run" kann die Generierung der Dokumentation gestartet werden, indem man den Button "Run doxygen" benutzt. Mithilfe des Buttons "Show HTML output" kann die erstellte Dokumentation auch gleich angezeigt werden.
Code Dokumentieren
Wichtig ist, dass der Code richtig dokumentiert ist.Ohne korrekte Dokumentation des Codes sieht man zwar, welche Klasse welche Methoden hat und welche Parameter gefordert werden, jedoch ist keine Beschreibung vorhanden.
Je nach dem welche Programmiersprache genutzt wird, müssen auch die Kommentare anders gekennzeichnet werden.
Wenn man das Visual Studio nutzt und mit C# programmiert, kann man einfach direkt vor der Klasse bzw. vor der Methode 3 Slashs einfügen, was dann einen Summery-Eintrag erstellt.
Der sieht folgendermassen aus:
Hier kann nun die Klasse bzw. die Methode beschrieben werden.
Das Wichtigste: Wozu wird sie verwendet? / Was kann sie?
Ebenfalls sollten die Parameter von den Methoden beschrieben werden. Hat eine Methode einen oder mehrere Parameter, wird für jeden Parameter unter die letzte Summary-Zeile diese Zeile angefügt:
Hier kann nun der entsprechende Parameter beschrieben werden.
Der Name wird vom gegebenen Namen für den Parameter und nicht von der Parameterklasse abgeleitet.
Hat man den Code sauber dokumentiert, generiert Doxygen eine sehr saubere Code-Doku. Am Anfang ist es etwas kompliziert, die Übersicht zu wahren, besonders wenn man ein grösseres Projekt dokumentieren liess. Hat man jedoch einmal den Durchblick mit der Navigation, ist es kein Problem mehr, das Gesuchte zu finden.
Keine Kommentare:
Kommentar veröffentlichen