Doxygen

Aus brainelectronics Wiki
Wechseln zu: Navigation, Suche

Installation

Linux

Vollen Umfang installieren (450MB)

   $ sudo apt-get install doxygen doxygen-doc doxygen-gui graphviz

Leichte Installation

   $ sudo apt-get install --no-install-recommends doxygen doxygen-gui

Zur Visualisierung von Abhängigkeiten (via Graphen) muss noch installiert werden:

   $ sudo apt-get install graphviz

Mac

   $ brew install doxygen

Oder direkter Download via Download Website

Benutzung

Grafisch

Für die Einfache Verwendung über die graphische Oberfläche eignet sich der "Doxywizard". Dieser besitzt nach der Installation keinen Menüeintrag, daher ist ein manueller Startvorgang über das Terminal notwendig:

   $ doxywizard

Im Menü ist alles einfachst einstellbar ;)

Nach dem Setup des Doxyfiles sollte dieses für die spätere Benutzung gespeichert werden.

Terminal

Ein grundlegendes Doxyfile kann mit folgendem Befehl erstellt werden:

   $ doxygen -g MySimpleDoxyfile

Die Dokumentation für das Projekt kann einfach erstellt bzw. aktualisiert werden:

   $ doxygen MySimpleDoxyfile

Einstellungen

Arduino Files

Sollen auch Arduino (.pde oder .ino) Files mit Doxygen verarbeitet werden, muss für diesen Filetyp ein Mapping durchgeführt werden. Siehe Stackoverflow Doxygen for ino Files

Unter "Project" im Doxywizard kann die Option "Extension Mapping" genutzt werden, wobei dort ino=c eingetragen wird.
Unter "Inut" im Doxywizard muss zusätzlich bei "File Patterns" der Eintrag *.ino hinzugefügt werden.
Im Doxyfile sieht dies folgendermaßen aus:

FILE_PATTERNS = [...] *.ino
EXTENSION_MAPPING = ino=c
 

Damit darf das File auch entsprechend .ino genannt werden.

/**@file sketch_1.ino */
 

Ansonsten besteht immer noch die Möglichkeit das File in .c umzubenennen und im @file entsprechend .c zu bezeichnen.

Code Styling

File Header

/**
 * @file       example_file.c
 * @author     brainelectronics (me@example.com)
 * @date       September, 2017
 * @version    1.2
 * @brief      Brief/short description of file.
 *
 * Detailed description of file.   
 */
 

Structs

/**
 * @brief      struct of Acceleration values measured by something
 */
typedef struct AccelerationValues
{
  float x;  /**< acceleration in x direction in m/s^2 */
  float y;  /**< acceleration in y direction in m/s^2 */
  float z;  /**< acceleration in z direction in m/s^2 */
};
 

Instances

Mit "@see" wird ein Hyperlink zur Definition angelegt.

/**
 * @brief      definition of the acceleration values struct
 * 
 * @see        AccelerationValues
 */
struct AccelerationValues accData;
 

Function Description

/**
 * @name    Example API Actions <- not used
 * @brief   Print Hello defined times and return true or false
 * @ingroup example <- not used
 *
 * This function prints 'Hello' to the console in a while
 * loop as long as the input variable is not zero. 
 * Finally it returns a random value of true or false.
 *
 * @param [in] repeat  Number of times to do nothing.
 *
 * @retval TRUE   Successfully did nothing.
 * @retval FALSE  Oops, did nothing not.
 *
 * Example Usage:
 * @code
 *    myExample(3); // Print 'Hello' 3 times.
 * @endcode
 */
int myExample(int repeat)
{
	while(repeat--)
	{
		printf("Hello\n");
	}

	return rand() % 2 == 1;
}
 

Credits

Graphviz ubuntuusers
Doxygen ubuntuusers
Arduino File Doxygen
Tips for Doxygen Documentation
Arduino Doxygen Example Page