(WS19-01)Wetterballon Entwicklung: Unterschied zwischen den Versionen

Aus Verteilte Systeme - Wiki
Wechseln zu: Navigation, Suche
(Formalia)
(Doxygen)
Zeile 10: Zeile 10:
 
[https://wwwvs.cs.hs-rm.de/vs-wiki/index.php?title=(WS19-01)Wetterballon_CSV CSV-Format]
 
[https://wwwvs.cs.hs-rm.de/vs-wiki/index.php?title=(WS19-01)Wetterballon_CSV CSV-Format]
   
==Doxygen==
+
= Doxygen =
  +
  +
== Zweck ==
  +
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>

Version vom 4. Dezember 2019, 14:06 Uhr

Formalia

C-Styleguide

Für die Entwicklung wurde sich auf einen gemeinsamen Styleguide geeinigt. Weiterer Text folgt.

Der Guide kann hier eingesehen werden: C-Styleguide

CSV

Die Sensordaten werden im zur einfacheren Auswertung im CSV-Format gespeichert. Nährere Informationen gibt es hier:

CSV-Format

Doxygen

Zweck

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

> **tl;dr:**  
> Immer `@brief`.  
> Optional ausführliche Beschreibung.

Ein Dokumentationsblock hat immer die folgende Form:

/**
 * Dokumentation...
 */

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.

/**
 * @brief Kurze Beschreibung.
 *
 * Eine längere optionale Beschreibung.<br/>
 * Diese kann mit @c HTML und Tags formatiert sein.
 *
 * @sa KONSTANTENNAME, funktionsname, variablenname
 */

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

> **tl;dr:**  
> Immer `@file` und `@brief`.  
> Bestenfalls `@author`.  
> Optional `@version` und ausführliche Beschreibung.

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.

/**
 * @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.
 */

Gruppendefinition

> **tl;dr:**  
> Immer `@defgroup` und `@brief`.  
> Optional ausführliche Beschreibung.

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.

/**
 * @defgroup g_test Testgruppe
 * @brief    Alle Testfunktionen.
 *
 * Diese Gruppe enthält alle Programmteile, die nur zur Demonstration von
 * Doxygen dienen.
 */

Code mit Dokumentation

> **tl;dr:**  
> Immer `@ingroup` und `@brief`.  
> Wenn Funktion mit Parametern `@param[]`.  
> Wenn Funktion mit Rückgabe `@return`.  
> Optional ausführliche Beschreibung und `@sa`.

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.

/**
 * @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);