Komentarze, które mają być przetwarzane przez Doxygena zaczynają się dwoma gwiazdkami lub trzema slashami:
/** Komentarz blokowy */ /// Komentarz jednolinijkowyKomentarz 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_parametruoraz wartość zwracaną, przez konstrukcję:
@return opisWaż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).
Poprzedni | Spis treści | Następny |
Dokumentowanie kodu w C | Początek rozdziału | Plik konfiguracyjny |