|
Doxygen jest narzędziem na licencji GNU General Public Licence i można go pobrać z www.doxygen.org.
Doxygen.exe jest programem obsługiwanym z linii poleceń. Pierwszym poleceniem, jakie należy wydać jest:
Zamiast <config_file> należy wpisać nazwę pliku konfiguracyjnego, który później będziemy edytować, np.:
|
UWAGA: Użycie polecenia doxygen -g bez parametru spowoduje utworzenie pliku konfiguracyjnego o nazwie Doxyfile.
|
Plik konfiguracyjny jest plikiem tekstowym i możemy go edytować w dowolnym edytorze (np. w notatniku).
Plik konfiguracyjny zawiera tagi wraz z wartościami oraz komentarze według następującej konwencji:
# TAG_DESCRIPTION
TAG_NAME = TAG_VALUE
Komentarz umieszczany jest po znaku # i trwa do końca bieżącej linii. Białe znaki nie są interpretowane przez Doxygen'a i służą do przejrzystego formatowania pliku konfiguracyjnego.
|
UWAGA: Doxygen rozróżnia małe i wielkie litery. Nazwy tagów należy zawsze pisać wielkimi literami!
|
Załóżmy, że potrafimy już prawidłowo skomentować prostą klasę z kilkoma metodami. Na przykład taką:
/**
* \brief klasa ulamek
*
* klasa obiektow umozliwiajaca operacje na ulamkach zwyklych.
*
* \version wersja alfa
*/
class ulamek
{
private:
long int licznik; /**< Licznik ulamka */
long int mianownik; /**< Mianownik ulamka */
long int nwd(long int, long int);
public:
ulamek(long int = 1, long int = 1);
void pisz();
ulamek mnozenie(ulamek &);
};
/**
* \brief Oblicza najwiekszy wspolny dzielnik dwoch liczb.
*
* Pobiera dwie wartosci typu long int i zwraca wartosc typu long int.
*
* \param[in] a pierwsza liczba.
* \param[in] b druga liczba.
* \return najwiekszy wspolny dzielnik pierwszej i drugiej liczby.
* \attention jesli druga liczba jest rowna zeru, zwraca pierwsza liczbe.\n
* jesli pierwsza liczba jest rowna zeru, zwraca druga liczbe.\n
* jesli obie liczby sa rowne zeru, zwraca 1.
*/
long int ulamek::nwd(long int a, long int b)
{
int temp;
if (a < 0)
a = -a;
if (b < 0)
b = -b;
if (a == 0)
{
if (b == 0)
return 1;
else
return b;
}
else
{
if (b == 0)
return a;
}
if (a < b)
{
temp = a;
a = b;
b = temp;
}
while (a % b != 0)
{
temp = b;
b = a % b;
a = temp;
}
return b;
}
/**
* \brief Konstruktor mieszany.
*
* Tworzy obiekt klasy ulamek, automatycznie skracajac ulamek do
* najprostszej postaci za pomoca funkcji nwd().\n
* Jesli konstruktor zostanie wywolany bez argumentow,
* zostanie utworzony obiekt klasy ulamek o wartosciach:
* \c licznik \c = \c 1,
* \c mianownik \c = \c 1
*
* \param[in] a licznik ulamka (domyslnie przyjmuje wartosc 1).
* \param[in] b mianownik ulamka (domyslnie przyjmuje wartosc 1).
* \attention jesli jako argument zostanie podany mianownik rowny zeru,
* wypisze komunikat na ekranie i przyjmnie mianownik rowny 1.
*/
ulamek::ulamek(long int a, long int b)
{
long int temp;
if (b == 0)
{
cout << endl << "[BLAD DZIELENIA PRZEZ ZERO]" << endl;
b = 1;
}
temp = nwd(a, b);
licznik = a / temp;
mianownik = b / temp;
}
/**
* \brief Wypisuje na ekran zawartosc obiektu klasy ulamek.
*
* Wywolanie metody w pierwszej kolejnosci powoduje przejscie do nowej linii.
* W nowej linii wypisuje na ekran licznik i mianownik oddzielony ukosnikiem (slash).
*/
void ulamek::pisz()
{
cout << endl << licznik << "/" << mianownik;
}
/**
* \brief Mnozy przez siebie dwa obiekty klasy ulamek.
*
* Pobiera obiekt klasy ulamek, mnozy go przez obiekt, na rzecz ktorego metoda zostala wywolana
* i zwraca obiekt klasy ulamek do miejsca wywolania.
*
* \param[in] a obiekt klasy ulamek
* \return Zwraca obiekt klasy ulamek, bedacy wynikiem mnozenia argumentu wejsciowego
* przez obiekt, na rzecz ktorego metoda zostala wywolana.
*/
ulamek ulamek::mnozenie(ulamek &a)
{
long int licznik_new, mianownik_new;
licznik_new = licznik * a.licznik;
mianownik_new = mianownik * a.mianownik;
ulamek temp(licznik_new, mianownik_new);
return temp;
}
|
UWAGA: W powyższym przykładzie użyłem nie przedstawionych wcześniej komend specjalnych (słów rozpoczynających się lewym ukośnikiem).
Aby dowiedzieć się do czego służą i jak działają, zajrzyj do manuala na stronie www.doxygen.org.
|
Zapiszmy plik z kodem do katalogu, w którym znajduje się program doxygen.exe, pod nazwą ulamek.cpp.
W katalogu powinny teraz znajdować się trzy pliki:
-
doxygen.exe - program pobrany ze strony www.doxygen.org.
-
ulamek.cpp - plik programu z odpowiednio skomentowanym kodem (np. tak jak powyżej).
-
config.txt - utworzony przez nas wcześniej plik konfiguracyjny (poleceniem doxygen -g config.txt).
Teraz wystarczy tylko wydać polecenie:
W naszym przypadku:
i już możemy przeglądać automatycznie wygenerowaną dokumentację! Domyślnie generowana jest dokumentacja w formatach HTML oraz LaTeX. Obie wersje zapisywane są w katalogu bieżącym.
Domyślnie nie jest generowana dokumentacja prywatnych składowych klas. W naszym przykładzie skomentowaliśmy dwie zmienne prywatne klasy ulamek oraz jedną metodę prywatną tej klasy.
Aby były one widoczne w wygenerowanej dokumentacji należy ustawić poniższy parametr w pliku konfiguracyjnym:
Dla zachowania porządku, warto ustawić również nazwę i wersję projektu (wg. poniższego wzoru):
PROJECT_NAME = "Moj pierwszy projekt"
PROJECT_NUMBER = "wersja alfa"
|
UWAGA: Argumenty tagów składające się z więcej niż jednego słowa należy umieszczać w cudzysłowach!
|
Doxygen pozwala ustawić dużo więcej szczegółowych opcji. Oto opis kilku z nich:
OUTPUT_DIRECTORY = <ścieżka_dostępu>
- katalog wyjściowy dokumentacji
EXTRACT_STATIC = [YES/NO]
- określa, czy dokumentować statyczne składowe klas
CLASS_DIAGRAMS = [YES/NO]
- określa, czy generować diagram przedstawiający dziedziczenie klas
OPTIMIZE_OUTPUT_FOR_C = [YES/NO]
- określa, czy optymalizować dokumentację dla języka C
INPUT = <ścieżka_dostępu>
- ścieżka dostępu do plików źródłowych projektu
RECURSIVE = [YES/NO]
- określa, czy w podkatalogach znajdują się pliki źródłowe projektu
GENERATE_HTML = [YES/NO]
- określa, czy generować dokumentację w formacie HTML
GENERATE_LATEX = [YES/NO]
- określa, czy generować dokumentację w formacie LaTeX
Więcej dokładnie opisanych opcji znajdziesz w manualu dostępnym na stronie www.doxygen.org.
|
UWAGA: Dokument, który właśnie przeczytałeś jest jedynie wstępem do dalszego samodzielnego odkrywania tajników
niezwykle elastycznego narzędzia, automatycznie generującego dokumentację, jakim jest Doxygen. Kontakt z autorem:
między http://info.wsisiz.edu.pl/, a /doxygen/ jest mój login. Usuń z niego tyldę, na końcu dopisz małpę oraz wsisiz.edu.pl
|
|
|
|
|
