Składnia opisów w kodzie źródłowym własciwa dla Doxygena

Fragmenty przeznaczone dla Doxygena rozpoczynają się sekwencją '/**' i kończą '*/', dzięki temu są one wykrywane przez preprocesor języka C jako komentarz i pomijane w procesie kompilacji źródeł a z kolei łatwo wydzielane przez samego Doxygena.
Słowa kluczowe Doxygena są poprzedzone znakiem @, a odwołania do innych udokumentowanych elementów kodu poprzedza się znakiem #. Poniżej przedstawiona jest składnia z przykładami niezbędna do opisania podstawowych elementów w plikach źródłowych.

Opis plików źródłowych

@file - określenie nazwy pliku,
@anchor - nazwa 'zakotwiczenia', do którego można się odwoływać z innych miejsc tworząc linki,
@brief - skrócony opis treści zawartej w pliku,
@author - autor pliku,
@version - wersja pliku.

Przykład

/** @file semaphore.h
* @anchor sema
* @brief Semaphores
*
* @author Piotr Romaniuk, (c) ELESOFTROM
* @version 1.0 Feb 4, 2011
*
* A semaphore is one of synchronization object, it provides well-known mechanism for signalling
* between threads. The semaphore contains an internal counter initialized with a number
...
*/

Opis funkcji

Opis funkcji powinien znaleźć się przed definicją/deklaracją funkcji i zawierać następujące elementy:

@brief - skrócony opis funkcji (aż do pustej linii),
    dalszy opis jest traktowany jako opis rozszerzony.
@param[ in | out | in/out ] - wyliczenie parametrów funkcji (Uwaga: pomiędzy nazwą a znaczeniem nie należy umieszczać znaku myślnika),
    w nawiasie kwadratowym podaje się odpowiednio czy jest to parametr wejściowy, wynikowy, czy jest używany jako wejście i wyjście.
@return - opis zwracanej wartości przez funkcję.

Przykład

/** @brief Try to obtain semaphore
*
* The function tries to obtain semaphore but never blocks (waits) on it.
* The result of operation is returned by return code.
* @param[in] sem pointer to the semaphore structure
* @return #OS_STATUS_OK when semaphore has been obtained\n
* #OS_WOULD_WAIT if semaphore is busy and trial of waiting on it would block
*/

os_result_t os_sema_tryget( os_sema_t * sem );

W przykładzie widoczne jest odwołanie do dwóch kodów opisanych gdzie indziej: OS_STATUS_OK oraz OS_WOULD_WAIT, prawidłowa składnia linku wymaga użycia znaku # podczas odwoływania się.

Opis struktury

Ogólny opis struktury powinien znaleźć się przed jej deklaracją, natomiast opis pól można umieścić jako kontynuację linii, w których się znajdują (zwróć uwagę na sekwencję znaków /**<, w szczególności na znak mniejszości) .

@brief - skrócony opis struktury/pola,
Przykład:

/**@brief data type for state machine description */

Opis makrodefinicji

W zależności od rozdzaju makrodefinicji, jej opis może ją poprzedzać lub występować w linii definicji.

Przykład 1.

define OS_WAIT_INFINITE 0 /**<@brief symbol for infinite wait on semaphore */

Przykład 2.

/** @brief Macro releases the semaphore.
*
* @note Use it only in ISR.\n
* @note may throw os_bug if semaphore counter overflows.
* @param[in] sem the pointer to the semaphore structure
* @return always returns #OS_STATUS_OK
*/

#define os_sema_post_intr( sem ) os_sema_post_common( sem , 1 )

Opis definicji typu wyliczanego (enum)

Przykład

/** @brief Thread state.
*
* The values for thread state description.
*/
enum os_thread_state_e{
OS_THREAD_WAIT = 1, /**<@brief Thread is waiting on some waiting object. It cannot be scheduled */
OS_THREAD_READY = 2,/**<@brief Thread is ready to be scheduled, but now higher priority thread is running */
OS_THREAD_RUNNING = 3/**<@brief Thread is running, its context is current */
};

Inne słowa kluczowe

@anchor - definiuje 'zakotwiczenie', do którego można się odwołać w opisach poprzez poprzedzenie nazwy znakiem #.
@warning - wyróżnione ostrzeżenie w dokumentacji,
@note - wyróżniona notka w dokumentacji,
@todo - wyróżniony opis wymagający wykonania (niedokończony, niezrealizowany),
@bug - wyróżniony opis błędu (nierozwiązanego),
@deprecated - oznaczanie elementów przestarzałych, które będą usunięte w kolejnych wersjach kodu.
Doxygen może utworzyć osobną stronę z listą błędów, ostrzeżeń, notatek i elementów do zrobienia oznaczonych powyższymi dyrektywami w kodzie źródłowym.
@code / @endcode - definiuje sekcję w opisie formatowaną jako kod źródłowy,
W opisach komentarza Doxygena można umieszczać składnię w formacie HTML, np. <br>, <b> </b>,
a także wstawiać obrazki, jak w HTMLu, poprzez <img src="nazwa-pliku">
@addtogroup / @{ / @} / @defgroup - definiowanie grup (odpowiadają znaczeniowo modułom złożonym z wielu plików źródlowych),
@mainpage / @page / @subpage - tworzenie oddzielnych stron włączanych potem do spisu treści w dokumentacji.

Konfiguracja opcji generowania dokumentacji (doxywizard)

Wygodnym interfejsem do konfiguracji opcji generowanej dokumentacji jest Doxywizard. Pozwala on na wskazanie położenia plików źródłowych, z których będzie generowana dokumentacja, katalogu wynikowego oraz wielu opcji określających poziom szczegółowości i wygląd dokumentacji. W szczególności możliwe jest zdefiniowanie symboli preprocesora, które będa interpretowane podczas tworzenia dokumentacji, co pozwala na warunkowe włączanie fragmentów, które będą widoczne tylko podczas kompilacji a ukrywane w dokumentacji.

Wygląd interfejsu do konfiguracji opcji Doxygena, w lewym dolnym panelu
widoczny jest aktywny help kontekstowy (po najechaniu myszką na opcję konfiguracji,
wyświetlany jest odpowiedni tekst pomocy, wyjaśniajacy znaczenie opcji)

Doxygen umożliwia również włączenie do dokumentacji kodu źródłowego uzupełnionego o aktywne linki do opisów zdefiniowanych elementów.

Przykładowy fragment dokumentacji z kodem źródłowym,
linie z wyróżnionym numerem na niebiesko (np. 00017, 00024)
są linkami prowadzącymi do opisów zdefiniowanych elementów.

Dopasowanie wyglądu dokumentacji

Doxygen pozwala na dopasowanie wyglądu dokumentacji, jest to możliwe poprzez określenie następujących elementów:

• plik loga,
• kolorystyka interfejsu,
• układ dokumentacji (forma pojedynczego pliku HTML albo układ oparty na ramkach)
• elementy dokumentacji (obecność funkcji do przeszukiwania, indeksu, spisów itp.),
• wskazanie własnego nagłówka i stopki w HTML, które będą odpowiednim fragmentem plików dokumentacji w HTMLu (zostaną one włączone na początku i końcu tworzonych plików - stanowiąc niejako ich opakowanie),
• własny zestaw stylów CSS - możliwość wpływania na kolorystykę, czcionki, itp.

Można również za pomocą zestawu prostych skryptów rozszerzyć proces budowania dokumentacji, zamieniając utworzone pliki w pliki PHP w celu uzyskania dodatkowych funkcji (np. ochrony dostępu do dokumentacji poprzez logowanie i rejestrację użytkowników, albo włączenie innych elementów tworzonych dynamicznie).

Linki