Codedokumentation mit doxygen und eclox

Inhaltsübersicht

  1. [Toolchain installieren] 
  2. [Eclipse und CDT installieren]
  3. [GNU ARM Eclipse installieren]
  4. [ST-Link und OpenOCD installieren sowie das erste Beispielprojekt]
  5. [Packs mit Mikrocontroller und Boarddaten laden]
  6. [Registerview auf Basis der Packs verwenden]
  7. [STM32CubeMX]
  8. [MinGW installieren]
  9. [unity verwenden]
  10. [Codedokumentation mit Doxygen, Eclox und GraphViz]

Quellcodedokumentation

Vielen Entwicklern macht es keinen Spaß zu dokumentieren. Die Programmierung ist durch, das Programm arbeitet und der Nutzer oder Kunde ist zufrieden. Und jetzt noch Doku schreiben? Wenn es sein muss.

Ideal ist es natürlich, wenn man ständig an der Doku arbeitet, indem man einfach arbeitet, besser gesagt programmiert. Dazu gibt es gute Planungstools, die als Dokumentation verwendet werden können und daraus ebenfalls Code ableiten (z.B. UML, Simulink). Auch Testfälle stellen eine gute Dokumentation dar, da sie nicht nur beschreiben, wie etwas getan werden muss, sondern programmierte und ausführbare Anwendungsbeispiele der Software darstellen (insbesondere bei Bibliotheken). Besonders wichtig für die Dokumentation von Quelltexten ist der Quelltext ansich. So werden Variablen- oder Unterprogrammnamen nicht zufällig, sondern genau passend beschrieben (statt int i; besser int abstandSensor;). 

Weiterhin gibt es Möglichkeiten Beschreibungen in den Quelltext einzubinden. Dazu gehören beispielsweise die Funktionsbeschreibung jedes Unterprogrammes und deren Parameter. Auch ist es sinnvoll den Autor, Erstelldatum und Lizenzdaten direkt in den Quellcode zu integrieren. Sie sind somit bei der Weitergabe des Codes immer vorhanden (auch an das eigene Ich in der Zukunft).

[Doxygen] bietet so eine Möglichkeit, Es können im Quelltext bestimmte Schlüsselwörter verwendet werden, die für die Beschreibung verwendet werden können. Daraus können anschließend Dokumentationsdateien erzeugt werden. Diese sind beispielsweise html- oder LaTex-Dateien. Für die Verwendung innerhalb von eclipse gibt es das Plugin [eclox] um es direkt zu verwenden.

Dieses Tutorial beschreibt die Installation von doxygen, eclox und GraphViz in eclipse. Anschließend wird ein triviales Beispiel gezeigt. 

Doxygen installieren

1. Doxygen [hier] downloaden.

2. Installation starten.


3. Lizenz lesen und bei Gefallen zusagen. Sonst kann es nicht installiert werden.


4. Den Installationsort auswählen. In diesem Fall wurde doxygen in den Ordner c:\stm32tc\doxygen installiert.

5. Alle Komponenten und Funktionen installieren.

6. Installation abschließen, indem die Standardeinstellungen verwendet werden., 






Jetzt ist Doxygen installiert. Es geht weiter mit dem eclox-Plugin für eclipse.

Eclox installieren

1. Installation unter eclipse durch Verwendung einer Downloadadresse durchführen. In eclipse unter Help den Punkt Install new Software auswählen.

2. Die Adresse http://download.gna.org/eclox/update in Work with eintragen und mit Enter bestätigen. Dann kommt nach ein paar Sekunden im unteren Fenster die Möglichkeit eclox auszuwählen. In diesem Beispiel wurden beide gewählt.

3. Die Installation mit Next bestätigen und die nächsten Schritte durchführen.




4. Nun muss eclipse nochmal neu gestartet werden, dann ist das Plugin installiert.

5. Zur Konfiguration von eclox in eclipse unter Window die Preferences aufrufen.

6. Dann auf der linken Seite Doxygen auswählen.

7. Dann im Preferences Fenster mit Add einen neuen Ordner für die Installation von Doxygen hinzufügen. In diesem Beispiel wird der Ordner c:\stm32tc\doxygen\bin ausgewählt.

8. Nun noch die neu hinzugefügte Version auswählen, damit diese verwendet werden kann.

Nun ist das Plugin für eclipse installiert.

GraphViz installieren - Graphen in doxygen darstellen


GraphViz ist notwendig, um grafische Call-Graphs darzustellen. Es muss extra installiert werden.

1. Herunterladen von GraphViz unter http://www.graphviz.org/ und Downloads links.

2. Es muss komplett nach unten gescrollt werden und die Lizenz akzeptiert (Accept) werden.

3. Dann die ausführbare Datei für Windows auswählen.

4. Dann die stabile Version auswählen und herunterladen.

5. Die heruntergeladene Datei ausführen und die Installation starten.


 6. Den Installationsort auswählen. Dabei darauf achten, dass keine Leerzeichen enthalten sind. Im Beispiel wird unter c:\stm32tc\Graphviz2.38 verwendet.

7. Installation bestätigen und die nächsten Punkte durchgehen.



8. Graphviz muss nun noch in den Systemeinstellungen von Windows in die Path-Variable eingetragen werden. Dazu muss die Systemsteuerung geöffnet und der Punkt System ausgewählt werden. Dann kann links Erweiterte Systemeinstellungen ausgewählt werden. Anschließend muss Umgebungsvariablen ausgewählt werden.

9. Dann unter Path den Pfad für Graphviz hinzufügen. In diesem Fall ist der Ordner C:\stm32tc\Graphviz2.38\bin zu verwenden.

Eine einfache Nutzung von eclox


Zu jedem Projekt muss eine doxygen Datei erstellt werden. Für diese gibt es in Eclipse durch eclox einen Editor.

1. Zum Erstellen dieser Datei, muss in Eclipse für ein Projekt diese der eclox-Button aufgerufen werden.


2. Nun kommt die Frage, ob eine neue doxygen-Datei angelegt werden soll. Dies mit Yes bejahen.

3. Es wird ein Namensvorschlag für die Datei erstellt. Dieser ist recht sinnvoll und kann beibehalten werden.


4. Die Datei wird jetzt angelegt und kann durch einen Doppelklick aufgerufen werden. Der Editor wird geöffnet.


5. Jetzt müssen die Einstellungen vorgenommen werden. Dazu wird ein Projektname vergeben, Scan recursively auswählen, Optimize for C auswählen, Use dot tool und alle Parameter ausgewählt. Alle Änderungen speichern.

6. Zum Ausführen von Doxygen kann erneut auf das eclox-Symbol geklickt werden.

7. Das Erstellen der Dokumentation wird gestartet. Sie befindet sich im Ordner docs.

8. Um etwas zu sehen, muss in wenigstens einer Quelldatei doxygen-Syntax verwendet werden, um die Dokumentation zu erstellen. Im Beispiel wird das Blinky-Beispiel verwendet. In der main.c wird eine Dateibeschreibung hinzugefügt. Die Dokumentation wird mit /*! eingeleitet. Unterschiedliche Schlüsselwörter können verwendet werden. Beispielsweise \file oder \author.

9. Nach dem Erstellen der Dokumentation gibt es im Ordner docs den Unterordner html. In diesem gibt es die Datei index.html, welche den Einstiegspunkt in die Dokumentation darstellt. Die Abbildung zeigt ein Beispiel.

Für die Einführung in Doxygen gibt es eine Reihe an guten Anleitungen und Tutorials im Internet. Diese stellen eine wichtige Basis für die weitere Dokumentation dar. Folgende Quellen können verwendet werden:








Keine Kommentare:

Kommentar veröffentlichen