Tworzenie dokumentacji w systemie Doxygen Paweł Strużyński 25 maja 2011

Plan prezentacji O systemie Doxygen Podstawy Dokumentowanie kodu Przykład kodu skomentowanego dla systemu Doxygen Podsumowanie

O systemie Doxygen

Doxygen – co to jest ? Doxygen jest systemem dokumentowania oprogramowania pisanego w C++, C, Java, C# i wiele innych. System ten może generować dokumentację w HTML oraz źródła dla LATEX’a. Dokumentacja może mieć format RTF, PostScript, PDF, skompresowanego HTML oraz stron podręcznika w systemie UNIX dla programu man. Doxygen jest tworzony dla systemu Linux i Mac OS w oparciu o bibliotekę Qt. Oprogramowanie to jest przenośne. Może być uruchomione pod system UNIX i jego klonami. Dostępne jest również w postaci binarnej dla system MS Windows.

Skład Doxygen’a doxygen – program generujący dokumentację na podstawie utworzonego wcześniej pliku konfiguracyjnego i przeglądanych plików (źródeł programów i nie tylko). doxytag – program pomocniczy pozwalający ingerować zewnętrzną dokumentację (do której doxygen nie ma bezpośredniego dostępu) z dokumentacją tworzoną przez doxygen. doxywizard – graficzna aplikacja ułatwiająca tworzenie pliku konfiguracyjnego dla dokumentacji danego projektu. Komponenty stowarzyszone: graphviz – oprogramowanie wykorzystywane do tworzenia rysunków grafów.

Podstawy

Pierwsze kroki Wygenerowanie pliku konfiguracyjnego: # doxygen -g lub # doxygen -g twoj_plik Pierwsza opcja generuje plik o standardowej nazwie Doxyfile. Drugi wariant pozwala zdefiniować plik o zadanej przez nas nazwie. Generowanie dokumentacji: # doxygen nazwa_pliku - wygeneruje nam dokumentację zgodnie z konfiguracją określoną w pliku nazwa_pliku

Rozszerzone tworzenie dokumentacji: wersja HTML: doxygen -w html header.html footer.html stylesheet.css wersja LATEX: doxygen -w latex header.tex doxygen.sty

Rodzaje dokumentacji Dostępne rodzaje dokumentacji: HTML – dokumentacja w postaci stron HTML, do których przeglądania używamy przeglądarki internetowej, np. Mozilla Firefox lub Opera :-) Główny dokument to standardowo index.html. LATEX – dokumentacja w LATEX’u. Utworzona dokumentacja musi zostać jeszcze skompilowana przez LATEX’a, ale na szczęście Doxygen tworzy nam Makefile’a :-) RTF – w wyniku otrzymujemy plik rtf, który możemy otworzyć np. w MS Wordzie.

XML – otrzymujemy zbiór plików xml- owych. Plikiem głównym jest index.xml. MAN – znany z systemów unixowych plik manuala.

Dokumentowanie kodu

Komentarze blokowe Styl JavaDoc: /** *... text... */ Styl Qt: /*! *... text... */ Środkowe * są w obu przypadkach opcjonalne, więc wystarczy: /*!... text... */

Styl C++: /// ///... text... /// lub: //! //!... text... //! Dla podniesienia widoczności można zastosować: /////////////////////// ///... text... ///////////////////////

Znacznik \brief Znacznik \brief pozwala nam oddzielić część główną komentarza od części szczegółowej, oddzielonej linią odstępu: /*! \brief Brief description. * Brief description continued. * * Detailed description starts here. */

Opisywanie zmiennych Do opisu zmiennych również mamy kilka różnych styli. Oto przykłady: int var; /*!< zmienna */ int var; /**< zmienna */ int var; //*< zmienna */ int var; ///< zmienna */ int var; //!< zmienna int var; ///< zmienna

Inne znaczniki w dokumentacji Znaczniki w dokumentacji zaczynają się od znaku \ lub więc mamy wybór. Możemy zadokumentować np. klasę Test. W tym celu używamy znacznika \class i wygląda to następująco: /*! \class Test \brief A test class. A more detailed class description. */

Listy Możemy tworzyć listy co znacznie ułatwia przedstawienie czegoś w punktach. /*! * A list of events: * - mouse events * -# mouse move event * -# mouse click event\n * More info about the click event. * -# mouse double click event * - keyboard events * -# key down event * -# key up event * * More text here. */ Efekt działania na następnym slajdzie.

A list of events: mouse events 1. mouse move event 2. mouse click event More info about the click event. 3. mouse double click event keyboard events 1. key down event 2. key up event More text here.

Grupowanie Doxygen pozwala nam też łatwo grupować elementy składowe naszego kodu. Każda grupa będzie się znajdować na osobnej stronie. Elementami grupy mogą być pliki, klasy, przestrzenie nazw, zmienne, itd. Do zdefiniowania grupy służy komenda \defgroup, użyta w komentarzu blokowym. Pierwszym argumentem jest unikalna etykieta, identyfikująca grupę. Drugim argumentem jest nazwa bądź tytuł grupy, który będzie użyty w dokumentacji. Odnośnik do elementu grupy tworzymy przez \ingroup.

Zamiast \defgroup możemy użyć \addtogroup – zapobiegamy tym ewentualnej pomyłce definiując dwie grupy o identycznej nazwie. Dla tej komendy tytuł jest opcjonalny: /** \addtogroup */ Odwołanie do grupy następuje poprzez komendę \ref : This is the \ref group_label ’’link’’ to this group.

Wzory matematyczne Robiąc dokumentację w Doxygen możemy dodawać także wzory w LATEX’u - opcja ta działa kiedy jako output wybierzemy LATEX lub HTML.

Przykład kodu skomentowanego dla systemu Doxygen

/** * Front controller. * Główna klasa, kontrolująca wszelkie działania aplikacji. FrontController musi być uruchamiany jako pierwszy. */ class FrontController implements IController { private $config; /** * Kontruktor front controllera. void void */ public function __construct() { $this->config = ConfigurationManager::getInstance(); } public function run() {... }

Podsumowanie

Podsumowanie Doxygen: jest bardzo wygodnym narzędziem bardzo ułatwiającym tworzenie dokumentacji projektów. Korzystając z tego programu oszczędzamy sporo czasu. jest na pewno bardzo pomocny przy pracy w zespołach programistycznych. dzięki niemu tworzymy przejrzysty kod programów, czytelny również dla innych osób.

Dziękuję za uwagę Dziękuję za uwagę