|
Komentowanie kodu w sposób zgodny ze standardem rozumianym przez Doxygen'a w niewielkim stopniu różni się od standardowego, stosowanego przez programistów sposobu komentowania kodu w języku C++.
Jest kilka sposobów komentowania kodu:
/*!
* ... komentarz ...
*/
/**
* ... komentarz ...
*/
///
/// ... komentarz ...
///
//!
//! ... komentarz ...
//!
Doxygen wykorzystuje dwa rodzaje opisu fragmentu kodu:
- Opis krótki
- Opis szczegółowy
Zaleca się wyszczególnianie opisów krótkich i opisów szczegółowych. Jest na to kilka spsobów:
/*!
* \brief Opis krótki zaczyna się tutaj.
* Dalszy ciąg opisu krótkiego.
*
* Opis szczegółowy zaczyna się tutaj (po jednej pustej linii).
*/
/**
* Opis krótki, zakończony kropką.
* Opis szczegółowy zaczyna się po kropce (niekoniecznie w nowej linii).
*/
Pierwszy sposób wyszczególniania opisu krótkiego i opisu szczegółowego jest domyślny i
wymaga tylko zachowania jednej pustej linii między opisem krótkim i szczegółowym. Drugi sposób wymaga
ustawienia wartości parametru JAVADOC_AUTOBRIEF na YES w pliku konfiguracyjnym (więcej o pliku konfiguracyjnym).
Powyższe sposoby komentowania kodu można mieszać ze sposobami wyszczególniania opisu krótkiego i opisu szczegółowego.
Jednak nie wszystkie "mieszanki" są prawidłowo interpretowane przez Doxygen'a. Aby nie wprowadzać zbędnego zamieszania,
ograniczę się do wyżej przedstawionych i zalecam ich stosowanie.
|
UWAGA: Doxygen obsługuje więcej sposobów komentowania kodu. W tej publikacji chciałbym jednak
skupić się na samej idei używania Doxygena, dlatego ograniczyłem się do kilku sposobów przedstawionych wyżej.
Pełny zestaw rozumianych przez Doxygen'a sposobów komentowania kodu
znajdziesz w manualu dostępnym na stronie www.doxygen.org.
|
Komentarz do fragmentu kodu można umieszczać w dwóch miejscach względem komentowanego kodu:
- Przed komentowanym kodem
- Za komentowanym kodem
Przedstawione wyżej sposoby odnoszą się do komentarzy umieszczonych przed komentowanym kodem.
Aby Doxygen zrozumiał komentarz umieszczony za komentowanym kodem należy użyć znaku mniejszości przed komentarzem, tak jak w przykładzie poniżej:
int zmienna; /*!< To jest krótki opis zmiennej */
|
UWAGA: Umieszczanie komentarzy za komentowanym kodem jest dopuszczalne tylko w przypadku komentowania zmiennych i parametrów!
Nie można w ten sposób komentować plików, klas, unii, struktur, grup, przestrzeni nazw, enums.
|
W przypadku funkcji, oprócz komentarzy krótkich (ogólnych) i szczegółowych, warto również poświęcić kilka minut na udokumentowanie argumentów wejściowych i wyjściowych oraz zwracanych wartości.
Poniżej przykład poprawnie udokumentowanej funkcji z wykorzystaniem komend specjalnych (\param oraz \return):
/**
* Funkcja sprawdza, czy z trzech odcinków da się zbudować trójkąt.
* Pobiera trzy wartości typu int i zwraca wartość typu bool.
*
* \param[in] x długość pierwszego odcinka.
* \param[in] y długość drugiego odcinka.
* \param[in] z długość trzeciego odcinka.
* \return 1 jeśli da się zbudować trójkąt, 0 jeśli nie da się zbudować trójkąta.
*/
bool triangle(int x, int y, int z)
{
return (x < y+z) && (y < x+z) && (z < x+y);
}
Atrybut [in] umieszczony po komendzie \param jest atrybutem opcjonalnym, wskazującym że komentowany argument jest argumentem wejściowym funkcji (dostarcza danych do funkcji).
Jeśli na liście argumentów znajduje się argument przekazywany przez referencję lub za pomocą wskaźników (jest pobierany i zmieniany w trakcje działania funkcji), należy użyć atrybutu [in,out].
Jeśli argument nie wprowadza żadnych danych do fukncji, a jedynie funkcja zwraca wartość za pomocą argumentu, należy użyć atrybutu [out].
Oprócz poznanych komend specjalnych (\brief, \param, \return) Doxygen interpretuje komendy takie jak:
\author jeden lub lista kilku autorów danego fragmentu kodu
\version wersja komentowanego fragmentu kodu
\date data lub przedział czasowy tworzenia fragmentu kodu
\bug opis nie rozwiązanego w bieżącej wersji błędu
\warning ostrzeżenie przed szkodliwym działaniem tego fragmentu kodu
oraz wiele innych dokładnie opisanych w manualu dostępnym na stronie www.doxygen.org.
|
UWAGA: Jako, że znaki: &, $, @, #, <, > oraz % mają specjalne znaczenie dla Doxygen'a,
aby umieścić je w komentarzu, należy użyć tzw. lewego ukośnika (backslash) przed każdym z nich w następujący sposób: \&, \$, \@, \#, \<, \>, \%.
|
|
|
|
