C ++: Erstellen von Dokumentationen mit Doxygen - Dummies

Die meisten Programmierer hassen die Erstellung von Dokumentation noch mehr als sie es hassen, ihren eigenen Code zu kommentieren. Geben Sie Doxygen ein, wodurch Programmierer in die Kommentare Tags einbetten können, die später extrahiert werden können, um die Dokumentation zu erstellen.

Installation von Doxygen

Doxygen wird nicht mit Code:: Blocks geliefert (zumindest nicht in dieser Schrift). Sie müssen die richtige Version von Doxygen für Ihre Anwendung herunterladen. (Es gibt auch einen Link zur Doxygen-Website von der Website Code:: Blocks.) Nachdem Sie auf die Doxygenorg-Website gelinkt haben, können Sie zur Downloadseite navigieren und die Version von Doxygen für Ihr Betriebssystem finden, wie hier gezeigt:

Laden Sie die für Ihr Betriebssystem passende Version herunter und installieren Sie sie. Sie können die Standardwerte akzeptieren, aber denken Sie daran, wo der Installationsassistent die ausführbare Doxygen-Datei ablegt.

Starten Sie jetzt Code:: Blöcke. Wählen Sie DoxyBlocks → Einstellungen öffnen. Von dort wählen Sie die Registerkarte Allgemein und legen den Pfad zu Doxygen fest. (Dies ist der Pfad, den Sie im vorherigen Absatz notiert haben.) Der Standardpfad für Windows ist C: Program Filesdoxygenbindoxygen. exe. Machen Sie dasselbe für den Pfad zum Doxywizard. Hier ist der Standard für Windows C: Program Filesdoxygenbindoxywizard. exe . Sie können die anderen Werkzeuge leer lassen, da sie beim Generieren von Dokumentation im HTML-Format nicht benötigt werden.

Dokumentationskommentare hinzufügen

Doxygen verwendet spezielle Kommentare, um Schlüsselwörter zu kennzeichnen, mit denen das Werkzeug Dokumentation erstellen kann. Verwirrenderweise akzeptiert Doxygen mehrere verschiedene Standards, aber der Standard ist derjenige, der JavaDoc am ähnlichsten aussieht, der / ** Kommentar, was in Ordnung ist. (Sie können den Kommentarstil in einen anderen ändern, indem Sie DoxyBlocks → Einstellungen öffnen auswählen und dann die Registerkarte Kommentarstil auswählen.)

Um zu sehen, wie das funktioniert, platzieren Sie den Cursor am Anfang einer Funktion und wählen Sie DoxyBlocks → Blockkommentar (oder drücken Sie Strg + Alt + B). Ein Kommentar wie der folgende wird angezeigt (die folgenden Beispiele verwenden das Budget5-Programm, das im herunterladbaren Material unter www.dummies.com / extras / cplusplus angezeigt wird):

/ ** kurz * * param accList list & * return void * * / void getAccounts (liste & accList) {

Code:: Blöcke fügt einen Doxygen-Blockkommentar ein, der mit / ** beginnt. Doxygen weiß, dass dieser Kommentar zu der unmittelbar folgenden Funktionsdefinition gehört. Doxygen-Schlüsselwörter beginnen mit einem (umgekehrten Schrägstrich). Das Schlüsselwort kurz markiert die kurze Beschreibung der Funktion. Die Kurzbeschreibung kann sich über mehr als eine Zeile erstrecken.Dies sollte eine kurze Beschreibung der Funktion sein, die in tabellarischen Anzeigen erscheint.

Der Programmierer kann dies mit einer ausführlicheren Beschreibung verfolgen, die mit dem Schlüsselwort details gekennzeichnet ist. Diese detaillierte Beschreibung gibt eine ausführlichere Beschreibung der Funktion.

Viele der Doxygen-Schlüsselwörter sind optional. Insbesondere wird das Schlüsselwort Details angenommen, wenn Sie einen Absatz, der von der Beschreibung kurz getrennt ist, nur durch eine Leerzeile beginnen.

Darüber hinaus ist eine separate Zeile mit dem Schlüsselwort param gekennzeichnet, um jedes Argument der Funktion zu beschreiben. Schließlich beschreibt das Schlüsselwort return den von der Funktion zurückgegebenen Wert.

Beim Ausfüllen kann der Doxygen-Kommentar für getAccounts () wie folgt aussehen:

/ ** kurz getAccounts - gibt Konten von der Tastatur aus * Details Diese Funktion liest Eingaben von der Tastatur. * Für jedes eingegebene S oder C erstellt die Funktion ein neues * Savings oder Checking Account-Objekt und fügt es der * Account-Liste hinzu. Ein X beendet die Eingabe. Jede andere * Eingabe wird als Einzahlung (Zahlen größer als * 0) oder als Auszahlung (Zahlen kleiner als 0) angenommen. * * param accList list & die Liste der von getAccounts () * erstellten account * -Objekte return void * / void getAccounts (list & accList) {

Sie können in derselben Zeile auch einen Doxygen-Kommentar hinzufügen. Dies wird am häufigsten beim Kommentieren von Datenelementen verwendet. Platzieren Sie den Cursor am Ende der Zeile und wählen Sie entweder DoxyBlocks → Line Comment oder drücken Sie Strg + Alt + L. Füllen Sie nun eine Beschreibung des Datenmembers aus. Das Ergebnis erscheint wie im folgenden Beispiel auch aus Budget5:

double balance; / ** 

Generierung der Doxygen-Dokumentation
Doxygen kann Dokumentationen in verschiedenen Formaten generieren, einige (z. B. kompilierter HTML-Code) erfordern jedoch weitere Downloads. Das HTML-Format ist besonders bequem, da es nur einen Browser benötigt, um es anzuzeigen.
Die Standardeinstellung ist HTML, aber wenn Sie das Format ändern möchten, wählen Sie DoxyBlocks → Voreinstellungen öffnen, und wählen Sie dann die Registerkarte Doxyfile Defaults 2 aus. In diesem Fenster können Sie alle verschiedenen Formate auswählen, die Sie generieren möchten.
Bevor Sie die Dokumentation zum ersten Mal extrahieren, möchten Sie wahrscheinlich einige andere Optionen auswählen. Wählen Sie DoxyBlocks → Einstellungen öffnen und dann die Registerkarte Doxyfile Defaults. Vergewissern Sie sich, dass das Kontrollkästchen Alle extrahieren aktiviert ist. Wählen Sie als Nächstes die Registerkarte Doxyfile Defaults 2 und aktivieren Sie das Kontrollkästchen Class_Diagrams. Wählen Sie nun die Registerkarte Allgemein aus und aktivieren Sie das Kontrollkästchen HTML nach der Kompilierung ausführen. Klicken Sie auf OK, und fertig. (Sie müssen dies nicht erneut tun, da die Optionen in einer Datei namens doxyfile gespeichert sind.)
Wählen Sie DoxyBlocks → Dokumentation extrahieren, um die Dokumentation zu generieren und anzuzeigen. Nach einem ziemlich kurzen Intervall öffnet Doxygen Ihren Lieblingsbrowser mit einer Dokumentation wie der in der folgenden Abbildung gezeigten.
Doxygen ist nicht sehr benutzerfreundlich, wenn es um Eingabefehler geht. Manchmal stoppt Doxygen einfach die Erzeugung von Dokumentation zu einem bestimmten Zeitpunkt in Ihrer Quelle ohne ersichtlichen Grund.Überprüfen Sie den Sauerstoff. Protokolldatei, die sich im gleichen Verzeichnis wie die Doxydatei befindet, für Fehler, die während der Extraktion aufgetreten sind.
Die folgende Abbildung zeigt den Projektbrowser im linken Fenster, in dem der Benutzer innerhalb der Projektdokumentation navigieren kann. Auf der rechten Seite wurde die Funktion getAccounts () ausgewählt, um eine detailliertere Beschreibung zu erhalten. Die kurze Beschreibung wird in der ersten Zeile angezeigt, gefolgt von der detaillierten Beschreibung, den Parametern und dem Rückgabewert:

Die Klassendokumentation ist ähnlich gründlich wie der folgende Code-Ausschnitt zeigt.
/ ** class Konto * kurz ein abstraktes Bankkonto. * Details Diese abstrakte Klasse enthält * Eigenschaften, die für beide Kontotypen gelten: * Überprüfung und Einsparungen. Es fehlt jedoch der * concept-Abzug (), der * zwischen den beiden * / class-Konten unterschiedlich ist {

Die Dokumentation zu Account wird hier gezeigt:

Beachten Sie die Beschreibung unter Klasse Konto . Dies ist die kurze Beschreibung. Wenn Sie auf Mehr klicken, gelangen Sie zur detaillierten Beschreibung. Beachten Sie auch die grafische Darstellung der Vererbungsbeziehung zwischen Account , ihren übergeordneten Klassen und ihren untergeordneten Klassen.