17 czerwca 2025

C Użycie Doxygena do dokumentacji kodu

Doxygen i Doxyfile.

Plik konfiguracji doxygen "Doxyfile". Generowanie pliku: doxygen -g <config_file> Albo po prostu doxygen -g Odpalenie generowania dokumentacji: doxygen <config_file> Prawdopodobnie dostaniemy pustawego HTMLa i LaTeXa

W Doxyfile edytujmy EXTRACT_ALL = YES i odpalamy znowu doxygen -g <config_file> Tym razem dostaniemy wszystko. Nie jest to najlepszy sposób więc cofnijmy tę zmianę.

Doxyfile zawiera wpisy typu TAG_NAME=wartości lub TAG_NAME+=wartości Wartości są oddzielone znakami białymi, jeśli zawartość ma mieć w środku spację użyj cudzysłowu "...". Wiele linii można skleić backslashem \ na końcu linii. Komentarz: #komentarz albo ##komentarz doczepiony do TAG_NAME, lub na początku pliku lub na końcu. Zachowany przy regeneracji pliku.

PROJECT_NAME = Moj projekt
PROJECT_NUMBER = wersja dokumentacji
PROJECT_BRIEF = krótki opis projektu
PROJECT_LOGO max 200x55 plik zostanie skopiowany
PROJECT_ICON ikonka na karcie przeglądarki
OUTPUT_DIRECTORY bez wprowadzenia domyślnie bieżący katalog
JAVADOC_AUTOBRIEF = YES pierwsza linia do kropki. pytajnika? i wykrzyknika! będzie krótkim opisem. Inaczej wymaga komendy @brief
OPTIMIZE_OUTPUT_FOR_C = YES
GENERATE_TODOLIST domyślnie włączone, szuka @todo
INPUT folder lub pliki do przeskanowania, domyślnie bieżący katalog
HTML_OUTPUT dokumentacja generowana wewnątrz OUTPUT_DIRECTORY domyślnie "./html"
RECURSIVE = YES przeszukaj podfoldery
GENERATE_LATEX = NO chyba że planujesz pdf z ghostscriptem

Komendy w kodzie

Komendy zaczynają się od \ lub małpy @ dowolnie. Szczegółowy opis elemtu w stylu Javadoc, komentarz C zaczynający się dwoma gwiazdkami ** np:

/**
 * ... text ...
 */	

/**
... text ...
 */

działa też styl Qt i C++

/*!
 * ... text ...
 */	

/*!
... text ...
 */

///
/// ... text ...
///	

//!
//! ... text ...
//!

Krótki opis - komenda @brief lub \brief kończy się na końcu paragrafu, więc szczegółowy opis zaczyna się po pustej linii:

/** @brief Brief description.
 *         Brief description continued.
 *
 *  Detailed description starts here.
 */

Jeśli chcesz udokumentować składową pliku, struct, union, class lub enum, możesz chcieć dodać komentarz za nim. Użyj dodatkowego znaku mniejszości < w bloku komentarzu. Działa to też z parametrami funkcji:

int var; /**< Detailed description after the member */
int var; /*!< Detailed description after the member */
int var; //!< Detailed description after the member */
int var; ///< Detailed description after the member */

Dla parametrów funkcji lepiej użyć komendy @param, ale jak ktoś koniecznie chce można użyć inline. [in], [out], [in,out] opisują kierunek.

void foo(int v /**< [in] docs for input parameter v. */);

/**
 * Copies bytes from a source memory area to a destination memory area,
 * where both areas may not overlap.
 * @param[out] dest The memory area to copy to.
 * @param[in]  src  The memory area to copy from.
 * @param[in]  n    The number of bytes to copy
 */
void memcpy(void *dest, const void *src, size_t n);

/** Sets the position.
 *  @param x,y,z Coordinates of the position in 3D space.
 */
void setPosition(double x,double y,double z,double t)
{
}

Przykład

/**
 * @file hello.c
 * Main program file. 
 * Either this or EXTRACT_ALL = YES in Doxyfile
 */

#include "include/fun.h"

#define INPUT 2 /**< Inline description of INPUT. With JAVADOC_AUTOBRIEF previous sentence is the brief. */

/**
 * @brief     Short description.
 * @details   Here goes some longer description. With all the info et all.
 * @author    Adam
 * @author    Eve
 * @version   2.1.37
 * @date      2024-2025
 * @pre       Precondition eg.: First initialize the system.
 * @bug       eg.: Not all memory is freed when deleting an object of this class.
 * @warning   Improper use can crash your application
 * @copyright GNU Public License.
 * @see       fun
 * @todo      Use x for something.
 */
void main(void){
	int x = fun(INPUT);
}

input/fun.h:

#ifndef __FUN_H
#define __FUN_H

/**
 * @file fun.h
 * ^file command = include this file in the documentation.
 * Needed for without EXTRACT_ALL = YES in Doxyfile.
 */

#include <stdio.h>

/**
 * My text.
 */
#define TEXT "hello"

/**
 * Some enum.
 */
enum SOME_ENUM 
{ 
	HEY, /**< Howdy. */
	HO   /**< @todo Change to a non explicit name. */
};

/**
 * @brief Fun function.
 *
 * Prints defined earlier text, using printf.
 * see searches for references.
 * @see TEXT
 *
 * @deprecated Don't use.
 * @important Seriously!
 * @note If you really have to.
 * @param[in] input The memory area to copy from.
 * @return Returns '1'.
 */
int fun(int input) {
	printf(TEXT);
	printf("%d ", HO + 2);
	return 1;
}

#endif /* __FUN_H */