Zasady Programowania (Projektowanie) C++ - część 3 1/17 Doxygen - wprowadzenie

Transkrypt

1 Zasady Programowania (Projektowanie) C++ - część 3 1/17 Zasady Programowania (Projektowanie) C++ część 3 Temat: 1. Doxygen Program Doxygen jest narzędziem ułatwiającym tworzenie dokumentacji dla programów w C, C++, Javie i IDL. Z jego pomocą można automatycznie generować dokumentację w postaci stron HTML, dokumentu LaTeX-owego i w wielu innych formatach (np. RTF (Word), Man Pages, PDF). Dokumentacja jest tworzona na podstawie komentarzy zawartych w kodzie źródłowym. Pomaga to w zapewnieniu zgodności dokumentacji z kodem. Dodatkowo w przypadku programów wykorzystujących programowanie zorientowane obiektowo tworzone są graficzne diagramy przedstawiające hierarchie zależności między plikami i klasami. Doxygen można również wykorzystać do tzw. reverse engineering (analizowanie nie udokumentowanych projektów software'owych) oraz do uporządkowania napisanej aplikacji. Najnowszą wersję programu Doxygen dla różnych systemów operacyjnych (w tym Linux, Windows) można skopiować ze strony: Oczywiście Doxygen nie jest jedynym systemem do tworzenia dokumentacji, inne popularne aplikacje do automatycznego tworzenia dokumentacji to n.p. Niekomercyjne AutoDOC, Autoduck, Cocoon, CcDoc, CppDoc, Cxref, cxxwrap, Cxx2HTML, C2HTML, Doc++, DocClass, Epydoc, gtk-doc, HappyDoc, HeaderDoc, HTMLgen, HyperSQL, Javadoc, KDoc, Natural Docs, Perceps, phpdocumentor, PHPDoc, ReThree-C++, RoboDoc, ScanDoc, Synopsis, Tydoc, VBDOX Komercyjne DocBuilder, DocJet, Doc-o-matic, ObjectManual, Together, CC-Rider, VBXC

2 Zasady Programowania (Projektowanie) C++ - część 3 2/17 2. Instalacja W przypadku instalacji w systemie Windows tworzony jest automatycznie katalog z programem Doxygen (np. c:\program Files\Doxygen). Do późniejszego generowania dokumentacji przydać się może informacja o tym gdzie znajduje się plik wykonywalny doxygen.exe (zwykle w katalogu \bin np. c:\program Files\Doxygen\bin).

3 Zasady Programowania (Projektowanie) C++ - część 3 3/17 3. Konfiguracja Wszystkie informacje dotyczące konfiguracji Doxygen przechowuje w pliku zwyczajowo nazywanym Doxyfile. Plik ten powinien znajdować się w katalogu zawierającym projekt. Kolejne linijki pliku konfiguracyjnego zawierają informacje o odpowiedniej opcji konfiguracyjnej (znaczniku) i jego wartość w formacie: ZNACZNIK1 = WARTOSC ZNACZNIK2 = WARTOSC1 WARTOSC2 Plik Doxyfile może byc utworzony na dwa sposoby. Pierwszym z nich (zalecanym dla poczatkujących) jest możliwość skorzystania z programu konfiguratora, ktory ma nazwę Doxywizard. Po instalacji programu w systemie Windows odnosnik do tego programu powinien znaleźć się w menu Start w katalogu Doxygen. Po uruchomieniu programu Doxywizard pokazuje się okienko konfiguratora (rys.1.) Rysunek 1. Okno konfiguratora Doxywizard Korzystanie z konfiguratora wykonywane jest w czterech krokach.

4 Zasady Programowania (Projektowanie) C++ - część 3 4/17 Krok.1. Naleźy określic określić opcje programu które należy uwzględnić podczas tworzenia dokumentacji. Na poczatku należy skorzystać z opcji Wizard. Po jej wyborze pokaże się okienko z najważniejszymi informacjami konfiguracyjnymi (rys. 2) Rysunek 2. Okno Wizard (zakładka Project) Najważniejsze pola które należy wypełnić to Project name - nazwa projektu Project version or id -numer wersji podawany w dokumentacji Source code directory -katalog w którym znajduje się program Destination directory -katalog w którym ma znaleźć sie dokumentacja Ponieważ dokumentacja może wystepować w wielu różnych formatach, ich wybór okresla się w zakładce Output (rys.3). Znajduje się tam spis dostępnych formatów (HTML, Latex, Man pages, Rich Text Format). Ponieważ stosunkowo niewiele osób zna sposób formatowania i tworzenia dokumentów z wykorzystaniem systemu Latex, proponowana konfiguracja powinna zawierać głównie możliwość generowania dokumentacji w formacie RTF co pozwoli na późniejszą łatwą modyfikacje z wykorzystaniem MS Word lub OpenOffice oraz ewentualnie HTML.

5 Zasady Programowania (Projektowanie) C++ - część 3 5/17 Rysunek 3. Okno Wizard (zakładka Output) Dodatkowo należy określić wersję językową. W tym celu należy wybrać w okienku głównym opcję Expert i zaznaczyć interesujący nas język dokumentacji (zakładka Project, opcja OUTPUT_LANGUAGE) (rys 4.). Standardowo językiem dokumentacji jest język angielski, jednak istnieje możliwość wyboru polskiego języka dokumentacji. Rysunek 4. Okno Expert (zakładka Project)

6 Zasady Programowania (Projektowanie) C++ - część 3 6/17 Krok.2. Nalezy zapisać plik konfiguracyjny Doxyfile. Powinien on znajdować się w tym samym katalogu co dokumentowany program. Dodatkowo warto przestrzegać zasady aby w nazwach katalogów nie występowały polskie znaki. Krok.3. Należy określic katalog z którego uruchamia się doxygen, czyli katalog gdzie znajduje się plik wykonywalny doxygen.exe (np. c:\program Files\Doxygen\bin) Rysunek 5. Okno konfiguratora po określeniu wszystkich opcji Krok.4. Mając skonfigurowany plik Doxyfile i odpowiednio opisane pliki źródłowe (sposób opisu znajduje się w kolejnym rozdziale), można przystapić do generowania dokumentacji. W tym celu należy uruchomić doxygen przy pomocy przycisku 'Start'. W polu ('output produced by doxygen') wypisywane są wszystkie informacje dotyczące kolejnych etapów tworzenia dokumentacji.

7 Zasady Programowania (Projektowanie) C++ - część 3 7/17 W przypadku korzystania z konsoli należy wywołać program doxygen.exe z opcją -g doxygen -g Powoduje to utworzenie pliku konfiguracyjnego Doxyfile o domyślnych ustawieniach. Następnie przy pomocy dowolnego edytora tekstu należy zmienić ustawienia w pliku konfiguracyjnym. Spis najważniejszych opcji znajduje się w dodatku A. Tutaj podajemy tylko najważniejsze EXTRACT_ALL = YES OUTPUT_DIRECTORY INPUT FILE_PATTERNS - wygenerowanie dokumentacji do kodu, w którym nie ma umieszczonych specjalnych komentarzy. określa ścieżkę do katalogu wyjściowego. Domyślnie dokumentacja tworzona jest w katalogu bieżącym. określa pliki i katalogi, które mają być przeanalizowane przez Doxygena. Gdy nie jest ustawiony, brane są pliki z bieżącego katalogu. określa wzorce plików, które są wczytywane, np. *.c, *.h. Gdy nie podamy żadnych wzorców, będą czytane wszystkie pliki *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx *.h++ *.idl *.odl.

8 Zasady Programowania (Projektowanie) C++ - część 3 8/17 4. Opisywanie elementów programu Doxygen dołącza do dokumentacji tekst znajdujący się w specjalnie oznaczonych komentarzach w kodzie źródłowym. Możliwe są różne konwencje interpretowane przez Doxygen. W przypadku inaczej oznaczonych komentarzy nie będą one uwzględniane w generowaniu dokumentacji Konwencja Qt - umieszczamy na początku komentarza wykrzyknik: /*! *... text... Konwencja Javadoc - umieszczamy na początku dodatkową gwiazdkę /** *... text... Konwencja dla jednolinijkowych komentarzy z C++ - umieszczamy na początku dodatkowy ukośnik lub wykrzyknik /// ///... text... /// lub //! //!... text... /// Oprócz zwykłego opisu, można również dodać opis skrócony, który będzie się pojawiał przy nazwie funkcji lub klasy, na przykład: //! To jest opis skrócony /*! A to już jest pełny opis klasy... class Bigint {... }

9 Zasady Programowania (Projektowanie) C++ - część 3 9/17 Aby opisywać szczegółowo parametry przekazwane do funkcji, należy umieścić w komentarzu znacznik \param, jak w przykładzie: //! Krótki opis operatora /*! To jest operator wypisywania na ekran \param os strumień wyjściowy \param l1 liczba, którą wypisujemy ostream& operator<<(ostream & os, liczba & l1) Komentarze mogą znajdować się zaraz przed komentowanym elementem (funkcja, strukturą, klasą), po komentowanym elemencie lub w dowolnym innym miejscu jeżeli używamy komend strukturalnych doxygen. Komendy strukturalne: \class \struct \union \enum \fn \var \def \file \namespace oznacza, że dokumentowana będzie klasa oznacza, że dokumentowana będzie struktura oznacza, że dokumentowana będzie unia oznacza, że dokumentowane będzie wyliczenie oznacza że dokumentowana będzie funkcja dokumentowana będzie zmienna, wyliczenie lub definicja typu dokumentowane będzie makro dokumentowany będzie plik dokumentowana będzie przestrzeń nazw Podczas dokumentowania kodu mozna także skorzystać z dodatkowych komend, które poprawiają czytelność opisu i zgodnośc ze standartami

10 Zasady Programowania (Projektowanie) C++ - część 3 10/17 Inne komendy doxygena: \attention tekst \author lista autorów \date data \warning \bug tekst \note tekst \par nazwa_sekcji \return tekst \retval wartość opis \since tekst \todo tekst \version nr_wersji tworzy sekcje Uwaga (ang. Attention) i umieszcza w niej tekst dodaje sekcje Autor dodaje sekcję daty dodaje sekcje ostrzeżenień dodaje sekcję błędów dodaje sekcje notatek dodaje sekcje o podanej nazwie, w następnej linii zaczyna się tekst do tej sekcji opis wartości zwracanych opis wartości zwracanej pozwala określić od kiedy dana funkcja/klasa jest dostępna dodaje sekcje todo dodaje numer wersji \b słowo pogrubia wpisane słowo \c słowo zapisuje podane słowo za pomocą czcionki regularnej \code \endcode rozpoczyna blok kodu źródłowego kończy blok kodu źródłowego \e słowo zapisuje słowo za pomocą czcionki pochylonej \image format nazwaplikugraficznego \li dodaje plik graficzny, do dokumentacji o określonym formacie pozwala utworzyć prostą listę \\ pozwala zapisać znak \ \@ \& pozwala zapisać pozwala zapisać znak & w HTML-u \$ pozwala zapisać znak $

11 Zasady Programowania (Projektowanie) C++ - część 3 11/17 W celu okumentowania argumentów funkcji korzystamy z komendy \param: /** \brief Komentarz ogólny. Dalej komentarz ogólny Komentarz szczegółowy. \param p1 Opis parametru 1. \param p2 Opis parametru 2. Jeżeli chcemy utworzyć hiperłącze do innej funkcji związanej z tematem możemy wykorzystać komendę \see: /** \brief Komentarz ogólny. Dalej komentarz ogólny Komentarz szczegółowy. \param p1 Opis parametru 1. \param p2 Opis parametru 2. \see int funkcja2() W dokumentacji mozliwe jest też automatyczne generowanie odpowiednio opisanych wzorów matematycznych.

12 Zasady Programowania (Projektowanie) C++ - część 3 12/17 5. Przykład Przyjęto że przykładowy program znajduje się w katalogu c:/program, natomiast dokumentacja powinna znaleźć się w katalogu c:/program/dokumentacja Treść programu: Dla wszystkich par x, y gdzie x={ 5, 4,...,5 }, n wpisanych z klawiatury wartości y ( n jest stałą) drukować wartości x, y, F x, y, F 2 x, y 0.5. Funkcja F x, y jest liczona w następujący sposób f F x, y ={ 1 y f 2 x f 2 1 x f 1 f 2 y f 1 y f 2 x w p.p. (1) f 1 a =e a a c i=1 10 sin ia, c=rand 2,3,...,5 (2) 10 f 2 a =a! i =1 cos ia (3) Dokumentowanie kodu (przykłady) Dokumentowanie struktury /*! \brief struktura przechowująca informacje o dwóch współrzędnych struct TPunkt{ ///zmienna x int x; ///zmienna y int y; }; Dokumentowanie funkcji {ten komentarz pojawi się w dokumetacji} /*! \brief obliczanie funkcji f3 dwóch zmiennych \param x \param y \return argument x funkcji f3(x,y) argument y funkcji f3(x,y) wynik działania funkcji f3(x,y) double f3(int x, int y); {ten komentarz nie pojawi się w dokumentacji} //obliczanie wartosci funkcji f3

13 Zasady Programowania (Projektowanie) C++ - część 3 13/17 Dokumentowanie pliku /*! \file Unit2.cpp \brief plik zawierający funkcje matematyczne wykorzystywane w programie

14 Zasady Programowania (Projektowanie) C++ - część 3 14/17 6. Dodatek A Podstawowe opcje konfiguracyjne Opis najważniejszych opcji podstawowych: PROJECT_NAME PROJECT_NUMBER OUTPUT_DIRECTORY OUTPUT_LANGUAGE EXTRACT_ALL EXTRACT_PRIVATE EXTRACT_STATIC HIDE_UNDOC_MEMBERS HIDE_UNDOC_CLASSES BRIEF_MEMBER_DESC REPEAT_BRIEF ALWAYS_DETAILED_SEC FULL_PATH_NAMES STRIP_FROM_PATH CLASS_DIAGRAMS SOURCE_BROWSER INLINE_SOURCES STRIP_CODE_COMMENTS CASE_SENSE_NAMES SHORT_NAMES nazwa projektu wersja projektu katalog wyjściowy dla dokumentacji (katalog, w którym zostanie zapisana dokumentacja) język dokumentacji, możliwe wartości to: English, Brazilian, Chinese, Croatian, Czech, Danish, Dutch, Finnish, French, German, Hungarian, Italian, Japanese, Korean, Norwegian, Polish, Portuguese, Romanian, Russian, Slovak, Slovene, Spanish and Swedish określa czy mają być w dokumentacji nazwy klas funkcji i zmiennych, które nie posiadają opisu w kodzie źródłowym określa czy mają być dokumentowane prywatne składowe klas określa czy mają być dokumentowane statyczne składowe klas określa czy na różnych podsumowaniach/indeksach mają być widoczne nie udokumentowane składowe określa czy na różnych podsumowaniach/indeksach mają być widoczne nie udokumentowane klasy określa czy ogólne opisy składowych mają znajdować się w opisie (indeksie) klasy określa czy maja być powtarzane ogólne opisy przed szczegółowymi, jeżeli HIDE_UNDOC_MEMBERS i BRIEF_MEMBER_DESC są ustawione na NO to ogólne opisy nie są wstawiane jeżeli ALWAYS_DETAILED_SEC i REPEAT_BRIEF są ustawione na YES, określa czy doxygen ma generować opis szczegółowy nawet gdy istnieje jedynie opis ogólny określa czy nazwy plików mają być poprzedzane ścieżką dostępu (dotyczy także nazw plików nagłówkowych) jeżeli FULL_PATH_NAMES jest ustawiony na YES za pomocą STRIP_FROM_PATH można określić część ścieżki, która ma być pomijana określa czy doxygen ma generować diagram przedstawiający dziedziczenie pomiędzy klasami (HTML i LaTeX) określa czy należy generować listę plików źródłowych w dokumentacji określa czy dodawać kod źródłowy funkcji i klas do dokumentacji określa czy mają być ukryte komentarze w kodach źródłowych dodawanych do dokumentacji określa czy nazwy plików są wrażliwe na wielkość liter określa czy pliki dokumentacji mają mieć krótkie nazwy

15 Zasady Programowania (Projektowanie) C++ - część 3 15/17 HIDE_SCOPE_NAMES VERBATIM_HEADERS SHOW_INCLUDE_FILES JAVADOC_AUTOBRIEF INHERIT_DOCS INLINE_INFO SORT_MEMBER_DOCS DISTRIBUTE_GROUP_DOC TAB_SIZE ENABLED_SECTIONS GENERATE_TODOLIST GENERATE_TESTLIST GENERATE_BUGLIST OPTIMIZE_OUTPUT_FOR_ C SHOW_USED_FILES określa czy przy nazwach funkcji zapisywać nazwę klasy i o przestrzeni nazw, do której należy funkcja określa czy doxygen do dokumentacji każdej klasy ma dodawać dokładną kopię pliku nagłówkowego, w którym jest zadeklarowana określa czy należy dodawać listę plików nagłówkowych dodawanych przez dokumentowany plik określa czy doxygen ma interpretować ogólne opisy w stylu JavaDoc określa czy jeżeli dana składowa nie posiada dokumentacji w kodzie, a reimplementuje inną udokumentowaną składową to czy należy wstawić dokumentacje udokumentowanej składowej określa czy przed składowymi typu inline należy umieszczać tekst [inline] określa czy doxygen ma dokumentować składowe zgodnie z porządkiem alfabetycznym ich nazw jeżeli zostało użyte grupowanie składowych w dokumentacji określa czy należy użyć opisów pierwszej zgrupowanej składowej dla całej grupy rozmiar tabulatora włącza i wyłącza sekcje dokumentacji określa czy generować listę todo (komenda \todo) określa czy generować listę testów (komenda \test) określa czy generować listę błędów (komenda \bug) określa czy optymalizować dokumentacje dla C określa czy dodawać listę plików, która została użyta do generowania dokumentacji Opcje dotyczące procesu generowania dokumentacji: QUIET WARNINGS WARN_IF_UNDOCUMENTE D WARN_FORMAT WARN_LOGFILE włącza / wyłącza komunikaty doxygena włącza / wyłącza wyświetlanie komunikatów z ostrzeżeniami określa czy wyświetlać komunikat z ostrzeżeniem jeżeli doxygen napotka nieudokumentowaną składową pozwala określić format ostrzeżeń pozwala określić plik do którego doxygen będzie zapisywał komunikaty o błędach Opcje dotyczące plików wejściowych: INPUT FILE_PATTERNS RECURSIVE EXCLUDE pliki źródłowe na podstawie, których należy generować dokumentacje (można także podać katalog), separatorem jest spacja pozwala filtrować pliki za pomocą wyrażeń regularnych np: *.cpp czy należy włączać do dokumentowania pliki z podkatalogów pozwala określić pliki lub katalogi które należy pominąć przy

16 Zasady Programowania (Projektowanie) C++ - część 3 16/17 EXCLUDE_PATTERNS EXAMPLE_PATH EXAMPLE_PATTERNS IMAGE_PATH INPUT_FILTER FILTER_SOURCE_FILES generowaniu dokumentacji pozwala filtrować pliki które należy pominąć za pomocą wyrażeń regularnych np.: *.o pozwala określić pliki lub katalogi, które zawierają przykładowe fragmenty kodu dodawane do dokumentacji za pomocą komendy \include jeżeli EXAMPLE_PATH zawiera katalogi można użyć EXAMPLE_PATTERNS do określenia plików ścieżka dostępu do plików graficznych które następnie mozna dodać do dokumentacji za pomocą komendy \image pozwala określić program filtrujący, który przefiltruje każdy plik wejściowy przed rozpoczęciem generowania dokumentacji określa czy filtrować pliki źródłowe za pomocą programu określonego w INPUT_FILTER Opcje dotyczące tworzenia alfabetycznego indeksu klas: ALPHABETICAL_INDEX COLS_IN_ALPHA_INDEX IGNORE_PREFIX określa czy doxygen ma tworzyć alfabetyczny indeks klas, struktur itd. pozwala określić liczbę kolumn w alfabetycznym indeksie klas, struktur pozwala określić prefiks, który ma być ignorowany przy tworzeniu alfabetycznego indeksu Opcje dotyczące dokumentacji generowanej w postaci HTML-u: GENERATE_HTML HTML_OUTPUT HTML_HEADER HTML_FOOTER HTML_STYLESHEET HTML_ALIGN_MEMBERS DISABLE_INDEX określa czy generować dokumentacje w postaci HTML pozwala określić katalog, w którym ma zostać wygenerowana dokumentacja w postaci HTML-u pozwala określić nagłówek HTML, jeżeli nie ustawione doxygen wygeneruje własny pozwala określić stopkę dla generowanej dokumentacji, jeżeli nie określone doxygen wygeneruje standardową stopkę pozwala określić plik styli css, które ma wykorzystywać dokumentacja określa czy położenie składowych ma być określane za pomocą tabeli (YES) czy wypunktowania (NO) pozwala wyłączyć generowanie na początku każdej podstrony dokumentacji indeksu ENUM_VALUES_PER_LINE określa liczbę wartości wyliczeń na linię tworzonej dokumentacji Najważniejsze opcje dotyczące dokumentacji generowanej w postaci LaTeX: GENERATE_LATEX określa czy ma być generowana dokumentacja w LaTeXie LATEX_OUTPUT katalog, w którym ma zostać wygenerowana dokumentacja w

17 Zasady Programowania (Projektowanie) C++ - część 3 17/17 LaTeXie Najważniejsze opcje preprocesora w doxygen: ENABLE_PREPROCESSING MACRO_EXPANSION określa czy doxygen ma przetwarzać dyrektywy preprocesora znalezione w dokumentowanym kodzie określa czy doxygen ma przetwarzać makra preprocesora