Doxygen. Bogdan Kreczmer.

Transkrypt

1 najważniejsze cechy Bogdan Kreczmer Zakład Podstaw Cybernetyki i Robotyki Instytut Informatyki, Automatyki i Robotyki Politechnika Wrocławska Kurs: Copyright c 2013 Bogdan Kreczmer Niniejszy dokument zawiera materiały do wykładu dotyczącego programowania obiektowego. Jest on udostępniony pod warunkiem wykorzystania wyłącznie do własnych prywatnych potrzeb i może on być kopiowany wyłącznie w całości, razem z niniejszą stroną tytułową.

2 najważniejsze cechy Niniejsza prezentacja została wykonana przy użyciu systemu składu L A TEX oraz stylu beamer, którego autorem jest Till Tantau. Strona domowa projektu Beamer:

3 najważniejsze cechy 1 najważniejsze cechy Ogólna charakterystyka Praca programu doxygen 2

4 Plan prezentacji najważniejsze cechy Ogólna charakterystyka Praca programu doxygen 1 najważniejsze cechy Ogólna charakterystyka Praca programu doxygen 2

5 Krótko o doxygen najważniejsze cechy Ogólna charakterystyka Praca programu doxygen Autor projektu: Dimitri van Heesch Strona projektu: jest systemem dokumentowania oprogramowania pisanego w C++, C, Java, Objective-C, Python, IDL, Fortran, VHDL, PHP, C# oraz D. System ten może generować dokumentację w HTML oraz źródła dla L A TEX a. Dokumentacja może mieć format RTF (MS-Word), PostScript, PDF (z hyper-łącznikami), skompresowanego HTML oraz stron podręcznika w systemie UNIX dla programu man. Dokumentacja może być generowana bezpośrednio ze źródeł, jak też plików stowarzyszonych z nimi. jest programem tworzonym dla systemu Linux i Mac OS w oparciu o bibliotekę Qt (doxywizard). Oprogramowanie to jest przenośne. Może być uruchomione pod systemem UNIX i jego klonami. Dostępne jest również w postaci binarnej dla systemu MS Windows.

6 najważniejsze cechy Ogólna charakterystyka Praca programu doxygen Projekty zdokumentowane z użyciem doxygen Obecnie ponad 377 bardziej znanych projektów wykorzystuje system doxygen do generowania dokumentacji. Jedne z bardziej znanych to: Adobe Open Source strona domowa projektów ASL (Adobe Source Libraries). KDE - dokumentacja różnych bibliotek. Samba OSCAR ( tworzy ogólną architekturę dla syrstemów robotycznych z ukierunkowaniem na roboty mobilne. XEngine ( silnik dla wizualizacji 3D w czasie rzeczywistym, jest on niezależny od platformy i typu API wykorzystywanego renderowania. Xerces C++ Parser biblioteka umożliwiająca pisanie aplikacji, które wymagają parsera plików XML.

7 najważniejsze cechy Ogólna charakterystyka Praca programu doxygen Przykładowe systemy tworzenia dokumentacji Niekomercyjne: AutoDOC Cocoon CcDoc Autoduck Natural Docs HappyDoc Doc++ Epydoc RoboDoc phpdocumentor C2HTML CppDoc KDoc ScanDoc HeaderDoc HyperSQL Javadoc Tydoc Synopsis Cxx2HTML DocClass gtk-doc Cxref Perceps ReThree-C++ PHPDoc cxxwrap VBDOX HTMLgen Komercyjne: CC-Rider Doc-o-matic Together VBXC DocJet ObjectManual DocBuilder

8 Plan prezentacji najważniejsze cechy Ogólna charakterystyka Praca programu doxygen 1 najważniejsze cechy Ogólna charakterystyka Praca programu doxygen 2

9 najważniejsze cechy kompnenty Ogólna charakterystyka Praca programu doxygen 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 integrować 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 towrzenia rysunków grafów. Strona projektu:

10 Przepływ informacji najważniejsze cechy Ogólna charakterystyka Praca programu doxygen

11 Plan prezentacji najważniejsze cechy 1 najważniejsze cechy Ogólna charakterystyka Praca programu doxygen 2

12 najważniejsze cechy Katalogi i rozmieszczenie plików

13 najważniejsze cechy Katalogi i rozmieszczenie plików Zakładamy, że w katalogu dox uruchamiamy aplikację doxywizard.

14 najważniejsze cechy Konfiguracja projektu okienko aplikacji doxywizard Ważniejsze ustawienia Katalog roboczy: Katalog ze źródlami: Przeglądanie katalogów:. (bieżący)../prj rekursywne

15 najważniejsze cechy Konfiguracja trybu pracy Ważniejsze trybu pracy Domyślnie w dokumentacji znajdą się tylko elementy, które są publiczne. (All Entities) W dokumentacji znajdą się również elementy, które nie są zdokumentowane. (Include cross-referenced...) W dokumentacji znajdzie się kod plików nagłówkowych wraz z odsyłaczami do definicji poszczególnych klas.

16 najważniejsze cechy Konfiguracja formatu generowanej dokumentacji Ważniejsze trybu pracy Domyślnie dokumentacja będzie generowana w podkatalogu html (zostanie on utworzony w trakcie pierwszego uruchomienia programu doxygen). (with frames...) Zostanie utworzone boczny rozwijalny indeks.

17 najważniejsze cechy Konfiguracja generacji diagramów Ważniejsze trybu pracy Jeśli mamy zainstalowany GraphViz dobrze jest zaznaczyć wszystkie rodzaje diagramów. Pozwoli to mieć pełną informację o strukturze programu i wzajemnych zależności między poszczególnymi metodami i funkcjami.

18 najważniejsze cechy Generowanie dokumentacji Faza generacji Gdy mamy wszystko ustawione, dobrze jest wcześniej zachować konfigurację do pliku, a następnie uruchomić fazę generacji dokumentacji.

19 najważniejsze cechy Rezultat uproszczonego zestawu ustawień Cechy wygenerowanej dokumentacji Korzystanie z uproszczonego trybu do zadawania ustawień konfiguracyjnych powoduje, że wygenerowana dokumentacja ma następujące wady: dodatkowe elementy opisu generowane przez doxygen są zawsze tylko w języku angielskim, nazwy plików są podawane z pełną ścieżką dostępu, dokumentacja nie jest generowana dla atrybutów klasy, które znajdują się w sekcji prywatnej. Jeżeli dokumentacja jest robiona dla użytkownika zewnętrznego, to jest to dobre rozwiązanie. Jednak jeśli robimy ją na własne potrzeby i chcemy mieć pełen zestaw informacji, to takie rozwiązanie jest niekorzystne. Aby usunąć te wady należy...

20 najważniejsze cechy Opcje rozszerzone sekcja Project Ustawienia projektu Należy przejść do zakładki Expert i wykonać następujące operacje: wybrać polską wersję jezykową. korzystnie jest odznaczyć ustawienienie REPEAT BRIEF (dzięki temu nie będzie powtarzany skrócony opis w pełnym opisie danego elementu), należy odznaczyć ustawienie FULL PATH NAMES (nazwy plików będą występowały bez pełnej ścieżki dostępu).

21 najważniejsze cechy Opcje rozszerzone sekcja Build Ustawienia sposobu generacji dokumentu korzystnie jest zaznaczyć ustawienienie EXTRACT PRIVATE, dzięki temu pojawi się dokumentacja elementów prywatnych klasy. wskazane jest również zaznaczenie ustawienia SHOW DIRECTORIES, pozwoli to mieć informację o strukturze katalogów, w których znajdują się dokumentowane pliki.

22 najważniejsze cechy Opcje rozszerzone sekcja Build Ustawienia sposobu generacji dokumentu korzystnie jest zaznaczyć ustawienienie EXTRACT PRIVATE, dzięki temu pojawi się dokumentacja elementów prywatnych klasy. wskazane jest również zaznaczenie ustawienia SHOW DIRECTORIES, pozwoli to mieć informację o strukturze katalogów, w których znajdują się dokumentowane pliki.

23 najważniejsze cechy Opcje rozszerzone sekcja Messages Ustawienia komunikatów warto zaznaczyć ustawienienie QUIET, dzięki temu w trakcie generacji dokumentacji nie pojawiają się komunikaty co jest tworzone (z punktu widzenia poprawności tworzonej dokumentacji zazwyczaj nie są one istotne), wskazane jest również zaznaczenie ustawienia WARN NO PARAMDOC, powoduje to generowanie ostrzeżeń, gdy jakieś parametry metody/funkcji lub wartość, którą zwraca, nie są zdokumentowane.

24 najważniejsze cechy Opcje rozszerzone sekcja Messages Ustawienia komunikatów warto zaznaczyć ustawienienie QUIET, dzięki temu w trakcie generacji dokumentacji nie pojawiają się komunikaty co jest tworzone (z punktu widzenia poprawności tworzonej dokumentacji zazwyczaj nie są one istotne), wskazane jest również zaznaczenie ustawienia WARN NO PARAMDOC, powoduje to generowanie ostrzeżeń, gdy jakieś parametry metody/funkcji lub wartość, którą zwraca, nie są zdokumentowane.

25 najważniejsze cechy Opcje rozszerzone sekcja Dot Ustawienia generacji diagramów dobrze jest zaznaczyć ustawienienie CLASS DIAGRAM, dzięki temu pozwoli to na umieszczenie w dokumentacji diagramów klas. Uwaga: nie jest korzystne zaznaczanie ustawienia UML LOOK. Powoduje to powstawanie bardzo szczegółowego diagramu, który staje się nieczytelny.

26 najważniejsze cechy Opcje rozszerzone sekcja Dot Ustawienia generacji diagramów dobrze jest zaznaczyć ustawienienie CLASS DIAGRAM, dzięki temu pozwoli to na umieszczenie w dokumentacji diagramów klas. Uwaga: nie jest korzystne zaznaczanie ustawienia UML LOOK. Powoduje to powstawanie bardzo szczegółowego diagramu, który staje się nieczytelny.

27 najważniejsze cechy Generacja dokumentacji - zakładka Run Generacja dokumentacji Jeśli wszystko jest dobrze, to w trakcie generacji dokumentu nie powinno być żadnych ostrzeżeń.

28 najważniejsze cechy Rezultat uproszczonego zestawu ustawień Cechy wygenerowanej dokumentacji Teraz mamy już opisy po polsku, zaś nazwy plików występują bez pełnej ścieżki dostępu.

29 Plan prezentacji najważniejsze cechy 1 najważniejsze cechy Ogólna charakterystyka Praca programu doxygen 2

30 najważniejsze cechy Strona tytułowa zdokumentowanego systemu

31 Lista plików najważniejsze cechy

32 najważniejsze cechy Opis pliku kwadrat.hh dla programu doxygen #ifndef KWADRAT_HH #define KWADRAT_HH /*! * \file * \brief Definicja klasy Kwadrat * * Plik zawiera definicję klasy Kwadrat, która * jest klasą pochodną i jest ona specjalizacją * klasy FiguraGeometryczna */ #include "figurageometryczna.hh"... #endif

33 najważniejsze cechy Opis pliku: kwadrat.hh

34 najważniejsze cechy Kod pliku (w dokumentacji): kwadrat.hh

35 najważniejsze cechy Opis pliku kwadrat.hh dla programu doxygen #ifndef KWADRAT_HH #define KWADRAT_HH /*! * \file * \brief Definicja klasy Kwadrat * * Plik zawiera definicję klasy Kwadrat, która * jest klasą pochodną i jest ona specjalizacją * klasy FiguraGeometryczna */ #include "figurageometryczna.hh" /*! * \brief Modeluje pojęcie kwadratu... */ class Kwadrat: public FiguraGeometryczna {... #endif

36 najważniejsze cechy Dokumentacja klasy Kwadrat

37 najważniejsze cechy Dokumentacja klasy Kwadrat

38 najważniejsze cechy Szczegółowy opis klasy Kwadrat i skrócone opisy metod /*! * \brief Modeluje pojęcie kwadratu * * Klasa modeluje pojęcie kwadratu o zadanej długości boku. * Jej atrybutem jest pole zawierające długość boku. * Przyjmuje się, że długość podawana jest w jednostkach * niemianowanych. */ class Kwadrat: public FiguraGeometryczna { public: /*! * \brief Inicjalizuje długość boku * * Inicjalizuje długość boku oraz wymusza wywołania konstruktora * klasy bazowej z identyfikatorem właściwym dla figury geometrycznej * typu kwadrat. * \param[in] DlugoscB - długość boku kwadratu. Jest ona zapisywana * w polu \link Kwadrat:: DlugoscBoku DlugoscBoku\endlink. */ Kwadrat(double DlugoscB): FiguraGeometryczna(TF Kwadrat), DlugoscBoku(DlugoscB) {}...

39 najważniejsze cechy Dokumentacja metody w klasie Kwadrat

40 najważniejsze cechy Opis metody w klasie Kwadrat /*! * \brief Modeluje pojęcie kwadratu * * Klasa modeluje pojęcie kwadratu o zadanej długości boku. * Jej atrybutem jest pole zawierające długość boku. * Przyjmuje się, że długość podawana jest w jednostkach * niemianowanych. */ class Kwadrat: public FiguraGeometryczna { public: /*! * \brief Inicjalizuje długość boku * * Inicjalizuje długość boku oraz wymusza wywołania konstruktora * klasy bazowej z identyfikatorem właściwym dla figury geometrycznej * typu kwadrat. * \param[in] DlugoscB - długość boku kwadratu. Jest ona zapisywana * w polu \link Kwadrat:: DlugoscBoku DlugoscBoku\endlink. */ Kwadrat(double DlugoscB): FiguraGeometryczna(TF Kwadrat), DlugoscBoku(DlugoscB) {}...

41 najważniejsze cechy Dokumentacja metody Kwadrat::ObliczPole()

42 najważniejsze cechy Opis skrócony metody w klasie Kwadrat w kwadrat.hh /*! * \brief Modeluje pojęcie kwadratu * * Klasa modeluje pojęcie kwadratu o zadanej długości boku. * Jej atrybutem jest pole zawierające długość boku. * Przyjmuje się, że długość podawana jest w jednostkach * niemianowanych. */ class Kwadrat: public FiguraGeometryczna { public:... /*! * \brief Wyznacza pole powierzchni kwadratu */ double ObliczPole() const;...

43 najważniejsze cechy Opis szczególowy przed definicją metody w kwadrat.cpp #include "kwadrat.hh" /*! * \file * \brief Definicja metody klasy Kwadrat * * Zawiera definicję metod klasy Kwadrat. */ /*! * Wyznacza pole powierzchni danego kwadratu * i zwraca jego wartość. * * \return Zwraca pole powierzchni kwadratu. Jest ono wyrażone * w jednostkach niemianowanych. */ double Kwadrat::ObliczPole() const { return DlugoscBoku* DlugoscBoku; }

44 najważniejsze cechy Opis szczególowy przed definicją metody w kwadrat.cpp #include "kwadrat.hh" /*! * \file * \brief Definicja metody klasy Kwadrat * * Zawiera definicję metod klasy Kwadrat. */ /*! * Wyznacza pole powierzchni danego kwadratu * i zwraca jego wartość. * * \return Zwraca pole powierzchni kwadratu. Jest ono wyrażone * w jednostkach niemianowanych. */ double Kwadrat::ObliczPole() const { return DlugoscBoku* DlugoscBoku; }

45 najważniejsze cechy Dokumentacja pliku kwadrat.cpp

46 najważniejsze cechy Kod pliku kwadrat.cpp w dokumentacji

47 najważniejsze cechy Dokumentacja pola Kwadrat:: DlugoscBoku

48 najważniejsze cechy Opis pola Kwadrat:: DlugoscBoku /*! * \brief Modeluje pojęcie kwadratu * * Klasa modeluje pojęcie kwadratu o zadanej długości boku. * Jej atrybutem jest pole zawierające długość boku. * Przyjmuje się, że długość podawana jest w jednostkach * niemianowanych. */ class Kwadrat: public FiguraGeometryczna { public:... private: /*! * \brief Długość boku kwadratu * * Pole zawiera długość boku kwadratu. Przyjmuje * się, że jest ona podana w jednostkach niemianowanych. */ double DlugoscBoku; };

49 najważniejsze cechy Dokumentacja typu wyliczeniowego

50 najważniejsze cechy Opis typu wyliczeniowego TypFiguryGeometrycznej /*! * \brief Rodzaj figury geometrycznej modelowanej przez daną klasę * * Wartości tego typu służą jako indentyfikatory dostępnych rodzai * figur geometrycznych. */ enum TypFiguryGeometrycznej { TF Zadna /*! Nie jest to żadna konkretna figura geometryczna */, TF Kwadrat /*! Figura geometryczna jest kawadratem */, TF Kolo /*! Figura geometryczna jest kołem */ };

51 najważniejsze cechy Wykorzystanie w dokumentacji środowiska verbartim

52 najważniejsze cechy Opis funkcji. Użycie środowiska verbatim /*! * \brief Wyświetla pole figury geometrycznej * * Funkcja wyświetla pole figury geometrycznej. Na podstawie * identyfikatora typu figury rozpoznaje, czy obiekt jest * częścią składową obiektu klasy Kolo, czy też Kwadrat, * lub czy jest to samodzielny obiekt klasy FiguraGeometryczna. * W zależności od tego wyświetla dokonuje właściwego rzutowania * i wylicza pole figury. Następnie wyświetlany jest komunikat, * w którym jest zawarta nazwa rodzaju figury oraz wartość jej pola, * np. \verbatim Kwadrat Pole = 10 \endverbatim * * \param[in] Figura - figura geometryczna, dla której ma zostać * wyświetlona wartość jej pola. */

53 Strona główna najważniejsze cechy

54 najważniejsze cechy Formatowanie strony głównej plik: strona.dox /*! \mainpage 2Ow1L - Bardzo Prosty Przykład Dwóch Rodzai Obiektów w Jednej Liście Aplikacja jest przykładem realizacji dwóch list bez korzystania z mechanizmów metod wirtualnych. Prowadzi to do dość siermiężnej konstrukcji, którą można zobaczyć w kodzie. \section etykieta-wazne-cechy Najważniejsze cechy Lista dwóch rodzai figur ukrywa wewnętrzną strukturę listy. Publiczny interfejs klasy udostępnia metody, które dodają kwadraty lub koła.\n Konstrukcja wspólnej listy bazuje na fakcie, że zarówno obiekty klasy Kwadrat, jak też obiekty klasy Kolo, są... */

55 najważniejsze cechy Formatowanie strony głównej plik: strona.dox /*! \mainpage 2Ow1L - Bardzo Prosty Przykład Dwóch Rodzai Obiektów w Jednej Liście Aplikacja jest przykładem realizacji dwóch list bez korzystania z mechanizmów metod wirtualnych. Prowadzi to do dość siermiężnej konstrukcji, którą można zobaczyć w kodzie. \section etykieta-wazne-cechy Najważniejsze cechy Lista dwóch rodzai figur ukrywa wewnętrzną strukturę listy. Publiczny interfejs klasy udostępnia metody, które dodają kwadraty lub koła.\n Konstrukcja wspólnej listy bazuje na fakcie, że zarówno obiekty klasy Kwadrat, jak też obiekty klasy Kolo, są... */

56 najważniejsze cechy Strona główna wariant z danymi autora

57 najważniejsze cechy Strona główna wariant z danymi autora plik: strona.dox /*! \mainpage 2Ow1L - Bardzo Prosty Przykład Dwóch Rodzai Obiektów w Jednej Liście \author Jan Kowalski \date \version 0.1 Aplikacja jest przykładem realizacji dwóch list bez korzystania z mechanizmów metod wirtualnych. Prowadzi to do dość siermiężnej konstrukcji, którą można zobaczyć w kodzie. \section etykieta-wazne-cechy Najważniejsze cechy Lista dwóch rodzai figur ukrywa wewnętrzną strukturę listy. Publiczny interfejs klasy udostępnia metody, które... */

58 najważniejsze cechy Wybrane sposoby zmiany stylu czcionki łamanie linii /*!... To jest przykład\n wymuszenia łamania linii. Odpowiada za to znak \\n. */

59 najważniejsze cechy Wybrane sposoby zmiany stylu czcionki pismo pochyłe /*!... To jest przykład wymuszenia \e pisma \e pochyłego. Odpowiada za to polecenie \\e. */

60 najważniejsze cechy Wybrane zmiany stylu czcionki pismo maszynowe /*!... To jest przykład \p pisma \p maszynowego. Odpowiada za to polecenie \\p. */

61 Plan prezentacji najważniejsze cechy 1 najważniejsze cechy Ogólna charakterystyka Praca programu doxygen 2

62 Linia polecenia najważniejsze cechy Dokumentację można wygenerować wywołując z linii polecenia program doxygen. W wywołaniu tym jako parametru należy użyć pliku (wraz ze ścieżką dostępu, o ile plik ten nie znajduje się w bieżącej kartotce), który zawiera konfigurację dla danej dokumentacji. Konsola: jkowalsk@panamint> doxygen Doxyfile

63 Linia polecenia najważniejsze cechy Lepszym jednak pomysłem jest stworzenie odpowiedniego pliku Makefile. Pozwala to przekierować wyjście standard error do pliku. Dzięki temu późnej można przeglądać wszystkie ostrzeżenia i komunikaty bez komunikatów informacyjnych generowanych przez program doxygen. Konsola: jkowalsk@panamint> make

64 najważniejsze cechy Przykładowa minimalna zawartość pliku Makefile Makefile start doxy : doxygen Doxyfile 2> doxy.log less doxy.log

65 najważniejsze cechy Koniec prezentacji Dziękuję za uwagę