|
|
| (Eine dazwischenliegende Version desselben Benutzers wird nicht angezeigt) |
| Zeile 12: |
Zeile 12: |
| | = Doxygen = | | = Doxygen = |
| | | | |
| − | == Zweck ==
| + | ...Cooler Text kommt noch... Infos zu Doxygen hier: [https://wwwvs.cs.hs-rm.de/vs-wiki/index.php/(WS19-01)Wetterballon_Doxygen Doxygen] |
| − | Dokumentation des Code ist wichtig. Aber auch viel Arbeit, da bei simplen Änderungen im Code möglicherweise auch die Dokumentation angepasst werden muss.
| |
| − | | |
| − | Doxygen leistet hierbei Unterstützung, indem es code-nahe Dokumentation ermöglicht. Der Entwickler kann direkt im Code die Funktionalität beschreiben und Doxygen erzeugt daraus eine ästhetisch ansprechende Dokumentation.
| |
| − | | |
| − | Dies gibt dem Entwickler auch die Möglichkeit mit verschiedenen Werkzeugen Zusammenhänge unterschiedlichster Art zu verdeutlichen, ohne dass Code auf unnatürliche Weise verschoben werden muss.
| |
| − | | |
| − | Auf der [Doxygen-Webseite](http://www.doxygen.nl/manual/) findet man zu jedem unten angesprochenen Punkt ausführliche Informationen.
| |
| − | | |
| − | == Struktur==
| |
| − | Der Großteil der Dokumentation sollte in Header-Dateien stehen, da diese die Funktionalität der implementierenden Quellcodedateien vorgeben, womit die C-Dateien austauschbar sind, die H-Dateien hingegen nicht.
| |
| − | | |
| − | Die Dokumentation ist nach folgender Struktur aufgebaut. Die einzelnen Punkte werden weiter unten erläutert.
| |
| − | | |
| − | * Dateibeschreibung.
| |
| − | * Gruppendefinitionen.
| |
| − | * Code mit Dokumentation (jeder Dokumentationsblock ist genau einer Gruppe zugeordnet).
| |
| − | | |
| − | C-Dateien sollten auch immer eine Dateibeschreibung enthalten.
| |
| − | | |
| − | == Elemente ==
| |
| − | | |
| − | === Mehrzeilige Kommentar (undokumentiert)===
| |
| − | | |
| − | Da Doxygen sich an die Kommentarsyntax von C halten muss, werden für die Dokumantation mehrzeilige Kommentare benutzt, die mit `/**` beginnen. Um normale mehrzeilige Kommentare zu verfassen, die nicht in die Dokumentation mit einfließen sollen, kann weiterhin `/*` als Startsymbol verwendet werden.
| |
| − | | |
| − | === Allgemein ===
| |
| − | <syntaxhighlight>
| |
| − | > **tl;dr:**
| |
| − | > Immer `@brief`.
| |
| − | > Optional ausführliche Beschreibung.
| |
| − | </syntaxhighlight>
| |
| − | | |
| − | Ein Dokumentationsblock hat immer die folgende Form:
| |
| − | <syntaxhighlight lang="c">
| |
| − | /**
| |
| − | * Dokumentation...
| |
| − | */
| |
| − | </syntaxhighlight>
| |
| − | | |
| − | Einzelne Inhalte können hervorgehomen werden, indem sie mit Tags versehen werden. Diese Tags beginnen mit einem `@` auf das ein Schlüsselwort folgt. Dabei gibt es wie in HTML Block-Tags und einfache Tags. In Block-Tags können einfache Tags verwendet werden. Um ein Block-Tag zu verlassen kann entweder ein neues begonnen werden oder mit einer Zeile Abstand weitergeschrieben werden.
| |
| − | | |
| − | In jedem Dokumentationsblock steht mindestens ein `@brief`-Tag mit einer kurzen Beschreibung, die nicht viel länger als eine Zeile ist, und unterhalb optional eine ausführlichere Beschreibung als Freitext. Über `@sa` ("*see also*") können Links auf andere Programmteile erstellt werden.
| |
| − | | |
| − | Texte können mit HTML und einfachen Tags formatiert werden.
| |
| − | <syntaxhighlight lang="c">
| |
| − | /** | |
| − | * @brief Kurze Beschreibung.
| |
| − | *
| |
| − | * Eine längere optionale Beschreibung.<br/>
| |
| − | * Diese kann mit @c HTML und Tags formatiert sein.
| |
| − | *
| |
| − | * @sa KONSTANTENNAME, funktionsname, variablenname
| |
| − | */
| |
| − | </syntaxhighlight>
| |
| − | | |
| − | Eine Übersicht und Erklärung zu allen Tags kann auf der Doxygen-Seite [Special Commands](http://www.doxygen.nl/manual/commands.html) gefunden werden (dort wird statt des `@` ein `\` verwendet).
| |
| − | | |
| − | === Dateibeschreibung ===
| |
| − | <syntaxhighlight>
| |
| − | > **tl;dr:**
| |
| − | > Immer `@file` und `@brief`.
| |
| − | > Bestenfalls `@author`.
| |
| − | > Optional `@version` und ausführliche Beschreibung.
| |
| − | </syntaxhighlight>
| |
| − | Die Dateibeschreibungsblöcke sind die einzigen Dokumentationsblöcke, die keiner Gruppe zugeordnet sind. Sie beschreiben eine Datei, indem der Dateiname und eine kurze Beschreibung angegeben wird.
| |
| − | | |
| − | Die Angabe der ursprünglichen Autoren ist erwünscht, da diese die Ansprechpartner zu Fragen zum Code sind.
| |
| − | | |
| − | Eine Versionsangabe der Datei ist ebenfalls möglich, aber nicht nötig. Es besteht wie immer die Möglichkeit der ausführlichen Beschreibung.
| |
| − | <syntaxhighlight lang="c">
| |
| − | /**
| |
| − | * @file testfile.h
| |
| − | * @brief Demonstration der Dokumentation mit Doxygen.
| |
| − | * @author Jonas Gaida, Max Mustermann
| |
| − | * @version 0.0.1
| |
| − | *
| |
| − | * Der Inhalt dieser Datei dient der Demonstration der Funktionsweise von
| |
| − | * Doxygen zum Dokumentieren von Code.
| |
| − | */
| |
| − | </syntaxhighlight>
| |
| − | | |
| − | === Gruppendefinition ===
| |
| − | <syntaxhighlight>
| |
| − | > **tl;dr:**
| |
| − | > Immer `@defgroup` und `@brief`.
| |
| − | > Optional ausführliche Beschreibung.
| |
| − | </syntaxhighlight>
| |
| − | | |
| − | Gruppendefinitionen erlauben die Gruppierung von Dokumentationsabschnitten in sinnvolle Abschnitte. Jede Gruppe hat einen internen Namen, der zum referenzieren dieser Gruppe dient, und einen Anzeigenamen, die beide hinter dem `@defgroup`-Tag angegeben werden.
| |
| − | <syntaxhighlight lang="c">
| |
| − | /**
| |
| − | * @defgroup g_test Testgruppe
| |
| − | * @brief Alle Testfunktionen.
| |
| − | *
| |
| − | * Diese Gruppe enthält alle Programmteile, die nur zur Demonstration von
| |
| − | * Doxygen dienen.
| |
| − | */
| |
| − | </syntaxhighlight>
| |
| − | | |
| − | === Code mit Dokumentation ===
| |
| − | <syntaxhighlight>
| |
| − | > **tl;dr:**
| |
| − | > Immer `@ingroup` und `@brief`.
| |
| − | > Wenn Funktion mit Parametern `@param[]`.
| |
| − | > Wenn Funktion mit Rückgabe `@return`.
| |
| − | > Optional ausführliche Beschreibung und `@sa`.
| |
| − | </syntaxhighlight>
| |
| − | Dokumentationen zu Code stehen immer unmittelbar vor dem dokumentierten Code. Dabei ordnen sie diesen einer Gruppe zu und beschreiben ihn kurz. Auf einen Parameternamen im Text kann mit vorangesetelltem `@p` hingewiesen werden.
| |
| − | | |
| − | Konstanten, Variablen und Datenstrukturen müssen ebenfalls dokumentiert werden. Dazu gehört auch die Dokumentation der einzelnen `enum`-Werte und `struct`- oder `union`-Felder.
| |
| − | | |
| − | Für Funktionen gibt es die Block-Tags `@param[]`, der einen Parameter und in den eckigen Klammern seine Funktion als `in`, `out` oder `in,out` beschreibt, und `@return`, der den Rückgabewert der Funktion erläutert. Diese werden immer benutzt, wenn eine Funktion die entsprechenden Eigenschaften besitzt.
| |
| − | | |
| − | Um Bezug auf andere Programmteile zu nehmen, gibt es das `@sa`-Block-Tag, das versucht jedes der Worte hinter ihm am Programmcode zu finden und in der Dokumentation zu verlinken.
| |
| − | <syntaxhighlight lang="c">
| |
| − | /**
| |
| − | * @ingroup g_test
| |
| − | * @brief Ersetzt alle Vorkommnisse von @p old in @p text durch @p new.
| |
| − | *
| |
| − | * Die Ersetzung erfolgt in-place.
| |
| − | *
| |
| − | * @param[in,out] text Text, in dem Buchstaben ersetzt werden.
| |
| − | * @param[in] old Zu ersetzender Buchstabe.
| |
| − | * @param[in] new Buchstabe, mit dem ersetzt wird.
| |
| − | * @return 0, wenn erfolgreich, sonst negativen Wert.
| |
| − | */
| |
| − | int test_replace(char *text, char old, char new);
| |
| − | </syntaxhighlight>
| |
Für die Entwicklung wurde sich auf einen gemeinsamen Styleguide geeinigt. Weiterer Text folgt.
Die Sensordaten werden im zur einfacheren Auswertung im CSV-Format gespeichert. Nährere Informationen gibt es hier:
