9.2. Komentowanie kodu

Komentarze, które mają być przetwarzane przez Doxygena zaczynają się dwoma gwiazdkami lub trzema slashami:

/** Komentarz blokowy */
/// Komentarz jednolinijkowy

Komentarz umieszczamy PRZED opisywaną funkcja, strukturą danych itp. Pierwsze zdanie (do kropki), służy jako krótki ogólny opis. Potem możemy napisać trochę szczegółów (jeśli trzeba). A na koniec opisujemy wszystkie parametry funkcji, używając konstrukcji:

@param nazwa opis_parametru

oraz wartość zwracaną, przez konstrukcję:

@return opis

Ważne, żeby opisy parametrów zawierały także informacje o dopuszczalnych wartościach, ewentualnie reakcji na nietypowe wartości itp. Cały opis funkcji (metody), może wyglądać tak:

/**
 * Funkcja nic nie robi (opis ogólny). Ta funkcja naprawdę nic nie robi
 * (opis szczegółowy).
 * @param par1 naprawdę wszystko jedno, co podasz
 * @param par2 też nie ma znaczenia
 * @return zawsze -18
 * @see coś_robi
 */
int nic_nie_robi(int par1, char *par2)
{
        return -18;
}

Użyto tu też konstrukcji @see, powodującej wygenerowanie linku do dokumentacji funkcji coś_robi.

Opis funkcji możemy podać zarówno w miejscu deklaracji, jak i definicji. Opisując typy (struktury danych) czasami wolelibyśmy umieszczać opisy pól struktury (klasy) po nich. Możemy robić to używając komentarza w postaci /**< ... */, w ten sposób:

/** Opis ogólny struktury ble. Opis szczegółowy. */
struct ble {
        int pole1;      /**< To jest pierwsze pole struktury ble */
        int pole2;      /**< A to jest drugie pole. */
};

W komentarzach można używać także innych dyrektyw postaci @costam, oraz większości tagów html-owych. Przedstawiona konwencja dokumentowania jest zgodna z JavaDoc, można także używać innych (np. Qt).