Dokumentation

Ist die Schnittstelle bekannt, so sollte bereits zu diesem Zeitpunkt die Schnittstelle dokumentiert werden. Zur Dokumentation wird doxygen verwendet.

Ordnerstruktur

Um die Schnittstellen Datei und die erste Dokumentation ablegen zu können wird eine minimale Ordnerstruktur erstellt.

: ~
$ mkdir -p inc doc/lib

Da in einem späteren Schritt auch andere Dokumentationen folgen werden, wird die Dokumentation der Bibliothek in einem eigenen Ordner angelegt.

Header Datei

Die Schnittstelle wird in einer eigenen .h Datei definiert und dokumentiert.

bubbleSort.h

#include <stdio.h>
#include <stdlib.h>

/**
 * @brief The bubbleSort() function sorts an array with "numberOfElements" 
 *        elements of size "sizeOfElement". The "base" argument points to
 *        the start of the array.
 *
 * The contents of the array are sorted in ascending order according to a
 * comparision function pointed to by "compare", which is called with two
 * arguments that point to the object being compared.
 *
 * The comparison function must return an integer less than, equal to, or
 * greater than zero if the first argument is considered to be respectively
 * less than, equal to, or greater than the second. If two members compare
 * as equal, their order in the sorted array is undefined.
 *
 * @param base base points to the begin of the array.
 * @param numberOfElements numberOfElements is equal to the number of elements
 *        stored within the array.
 * @param sizeOfElements sizeOfElement holds the size of one element of the
 *        array, in bytes.
 * @param compare compare is a function which returns an integer that
 *        represents the relative order of the passed keys.
 * @return bubbleSort() returns EXIT_SUCCESS on successful execution,
 *        EXIT_FAILURE otherwise.
 */
int bubbleSort(void *base, size_t numberOfElements, size_t sizeOfElement,
        int (*compare)(void const *firstKey, void const *secondKey));

Doxygen

Doxygen benötigt zur Erstellung der Dokumentation eine Konfigurationsdatei. Es kann eine standardisierte Konfigurationsdatei automatisch erstellt werden. Es reichen kleine Anpassungen aus um eine bereits befriedigende Dokumentation zu erhalten.

TODO

Standard C Doxyfile hinterlegen

Nun kann doxygen zum ersten Mal lokal ausgeführt werden, um die Formatierung zu prüfen.

: ~/bubbleSortLibrary/doc/lib 
$ doxygen config.doxy && make -C _bld/latex && xdg-open _bld/latex/refman.pdf

.gitignore anpassen

Da die Dateien welche durch dein Build-Prozess erstellt wurden nicht auf dem Repository verwaltet werden sollen. Wird eine neuer Eintrag der .gitignore Datei hinzugefügt.

.gitignore

# Build directories
_*/

Mit diesem Eintrag werden alle Ordner mit dem Präfix “_” von git ignoriert. Jeder Ordner der Dateien enthält, welche durch die übrigen Quellen erstellt werden können, wird vom Repository ausgeschlossen.

Nun kann der zweite Commit abgesetzt werden, dies wird nun für lange Zeit der letzte auf dem Master-Branch sein.

: ~/bubbleSortLibrary 
$ git commit -m "Add interface description and doxygen configuration file"