Doxygen system generowania dokumentacjikreczmer/kpo/materialy/dodatki/...Programowanie obiektowe...

Doxygen – najważniejsze cechyTworzenie dokumentacji

Doxygen – system generowania dokumentacji

Bogdan [email protected]

Zakład Podstaw Cybernetyki i RobotykiInstytut Informatyki, Automatyki i Robotyki

Politechnika Wrocławska

Kurs: Programowanie obiektowe

Copyright c©2012 Bogdan Kreczmer

Niniejszy dokument zawiera materiały do wykładu dotyczącego programowania obiektowego. Jest onudostępniony pod warunkiem wykorzystania wyłącznie do własnych prywatnych potrzeb i może on być kopiowanywyłącznie w całości, razem z niniejszą stroną tytułową.

Programowanie obiektowe Doxygen – system generowania dokumentacji


Niniejsza prezentacja została wykonana przy użyciu sys-temu składu LATEX oraz stylu beamer, którego autoremjest Till Tantau.

Strona domowa projektu Beamer:http://latex-beamer.sourceforge.net



Plan prezentacji

1 Doxygen – najważniejsze cechyOgólna charakterystykaPraca programu doxygen

2 Tworzenie dokumentacjiKonfiguracja generacji dokumentacji dla doxygenWygląd dokumentacja i jej źródełGenerowanie dokumentacji z linii polecenia



Ogólna charakterystykaPraca programu doxygen






Krótko o doxygen

Autor projektu: Dimitri van HeeschStrona projektu: http://www.doxygen.org

Doxygen 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 LATEX’a. Doku-mentacja 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 stowarzy-szonych z nimi.

Doxygen jest programem tworzonym dla systemu Linux i Mac OS w oparciu o biblio-tekę Qt (doxywizard). Oprogramowanie to jest przenośne. Może być uruchomionepod systemem UNIX i jego klonami. Dostępne jest również w postaci binarnej dlasystemu MS Windows.




Projekty zdokumentowane z użyciem doxygen

Obecnie ponad 377 bardziej znanych projektów wykorzystuje system doxygen do genero-wania dokumentacji.

Jedne z bardziej znanych to:

Adobe Open Source – strona domowa projektów ASL (Adobe Source Libraries).

KDE - dokumentacja różnych bibliotek.

Samba

OSCAR (http://www.oscar-net.org) tworzy ogólną architekturę dla syrstemówrobotycznych z ukierunkowaniem na roboty mobilne.

XEngine (http://xengine.sourceforge.net) “silnik” dla wizualizacji 3D w czasierzeczywistym, jest on niezależny od platformy i typu API wykorzystywanegorenderowania.

Xerces C++ Parser – biblioteka umożliwiająca pisanie aplikacji, które wymagająparsera plików XML.




Przykładowe systemy tworzenia dokumentacji

Niekomercyjne:

AutoDOC

HappyDoc

C2HTML

HyperSQL

DocClass

PHPDoc

Cocoon

Doc++

CppDoc

Javadoc

gtk-doc

cxxwrap

CcDoc

Epydoc

KDoc

Tydoc

Cxref

Autoduck

RoboDoc

ScanDoc

Synopsis

Perceps

VBDOX

Natural Docs

phpDocumentor

HeaderDoc

Cxx2HTML

ReThree-C++

HTMLgen

Komercyjne:

CC-Rider

DocJet

Doc-o-matic

ObjectManual

Together

DocBuilder

VBXC




Doxygen – kompnenty

doxygen - program generujący dokumentację na podstawie utworzonegowcześniej pliku konfiguracyjnego i przeglądanych plików (źródeł progra-mów i nie tylko).

doxytag - program pomocniczy pozwalający integrować zewnętrzną doku-mentację (do której doxygen nie ma bezpośredniego dostępu) z doku-mentacją tworzoną przez doxygen.

doxywizard - graficzna aplikacja ułatwiająca tworzenie pliku konfiguracyjne-go dla dokumentacji danego projektu.

Komponenty stowarzyszone:

graphviz - oprogramowanie wykorzystywane do towrzenia rysunków grafów.Strona projektu: http://www.research.att.com/sw/tools/graphviz/




Przepływ informacji



Konfiguracja generacji dokumentacji dla doxygenWygląd dokumentacja i jej źródełGenerowanie dokumentacji z linii polecenia






Katalogi i rozmieszczenie plików




Katalogi i rozmieszczenie plików

Zakładamy, że w katalogu doxuruchamiamy aplikację doxywizard.




Konfiguracja projektu – okienko aplikacji doxywizard

Ważniejsze ustawienia

Katalog roboczy: . (bieżący)Katalog ze źródlami: ../prj

Przeglądanie katalogów: rekursywne




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 . . .) Wdokumentacji znajdzie się kod plikównagłówkowych wraz z odsyłaczami dodefinicji poszczególnych klas.




Konfiguracja formatu generowanej dokumentacji


Domyślnie dokumentacja będziegenerowana w podkatalogu html(zostanie on utworzony w trakciepierwszego uruchomienia programudoxygen).

(with frames . . .) Zostanie utworzoneboczny rozwijalny indeks.




Konfiguracja generacji diagramów


Jeśli mamy zainstalowany GraphVizdobrze jest zaznaczyć wszystkierodzaje diagramów. Pozwoli to miećpełną informację o strukturzeprogramu i wzajemnych zależnościmiędzy poszczególnymi metodami ifunkcjami.




Generowanie dokumentacji

Faza generacji

Gdy mamy wszystko ustawione, dobrzejest wcześniej zachować konfiguracjędo pliku, a następnie uruchomić fazęgeneracji dokumentacji.




Rezultat uproszczonego zestawu ustawieńCechy wygenerowanej dokumentacji

Korzystanie z uproszczonego trybu do zada-wania ustawień konfiguracyjnych powoduje,że wygenerowana dokumentacja ma nastę-pujące wady:

dodatkowe elementy opisugenerowane przez doxygen sązawsze tylko w języku angielskim,

nazwy plików są podawane z pełnąścieżką dostępu,

dokumentacja nie jest generowanadla atrybutów klasy, które znajdująsię w sekcji prywatnej. Jeżelidokumentacja jest robiona dlaużytkownika zewnętrznego, to jestto dobre rozwiązanie. Jednak jeślirobimy ją na własne potrzeby ichcemy mieć pełen zestawinformacji, to takie rozwiązanie jestniekorzystne.

Aby usunąć te wady należy . . .




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ękitemu nie będzie powtarzanyskrócony opis w pełnym opisiedanego elementu),

należy odznaczyć ustawienieFULL PATH NAMES (nazwy plikówbędą występowały bez pełnejścieżki dostępu).




Opcje rozszerzone – sekcja Build

Ustawienia sposobu generacji dokumentu

korzystnie jest zaznaczyćustawienienie EXTRACT PRIVATE,dzięki temu pojawi siędokumentacja elementówprywatnych klasy.

wskazane jest również zaznaczenieustawienia SHOW DIRECTORIES,pozwoli to mieć informację ostrukturze katalogów, w którychznajdują się dokumentowane pliki.




Opcje rozszerzone – sekcja Messages

Ustawienia komunikatów

warto zaznaczyć ustawienienieQUIET, dzięki temu w trakciegeneracji dokumentacji niepojawiają się komunikaty co jesttworzone (z punktu widzeniapoprawności tworzonejdokumentacji zazwyczaj nie są oneistotne),

wskazane jest również zaznaczenieustawienia WARN NO PARAMDOC,powoduje to generowanieostrzeżeń, gdy jakieś parametrymetody/funkcji lub wartość, którązwraca, nie są zdokumentowane.




Opcje rozszerzone – sekcja Dot

Ustawienia generacji diagramów

dobrze jest zaznaczyć ustawienienieCLASS DIAGRAM, dzięki temupozwoli to na umieszczenie wdokumentacji diagramów klas.

Uwaga: nie jest korzystnezaznaczanie ustawienia UML LOOK.Powoduje to powstawanie bardzoszczegółowego diagramu, którystaje się nieczytelny.




Generacja dokumentacji - zakładka Run

Generacja dokumentacji

Jeśli wszystko jest dobrze, to w trakcie ge-neracji dokumentu nie powinno być żadnychostrzeżeń.




Rezultat uproszczonego zestawu ustawieńCechy wygenerowanej dokumentacji

Teraz mamy już opisy po polsku, zaś nazwyplików występują bez pełnej ścieżki dostępu.




Strona tytułowa zdokumentowanego systemu




Lista plików




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




Opis pliku: kwadrat.hh




Kod pliku (w dokumentacji): kwadrat.hh




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




Dokumentacja klasy Kwadrat




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) {}

...Programowanie obiektowe Doxygen – system generowania dokumentacji



Dokumentacja metody w klasie Kwadrat




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) {}

...Programowanie obiektowe Doxygen – system generowania dokumentacji



Dokumentacja metody Kwadrat::ObliczPole()




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;

...




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;}




Dokumentacja pliku kwadrat.cpp




Kod pliku kwadrat.cpp w dokumentacji




Dokumentacja pola Kwadrat:: DlugoscBoku




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;

};




Dokumentacja typu wyliczeniowego




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 */

};




Wykorzystanie w dokumentacji środowiska verbartim




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.*/




Strona główna




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 listbez 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 ukrywa wewnętrzną strukturęlisty. Publiczny interfejs klasy udostępnia metody, któredodają kwadraty lub koła.\nKonstrukcja wspólnej listy bazuje na fakcie, że zarównoobiekty klasy Kwadrat, jak też obiekty klasy Kolo, są...

*/




Strona główna — wariant z danymi autora




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 06.05.1012\version 0.1

Aplikacja jest przykładem realizacji dwóch listbez 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 ukrywa wewnętrzną strukturęlisty. Publiczny interfejs klasy udostępnia metody, które...

*/




Wybrane sposoby zmiany stylu czcionki — łamanie linii

/*!...

To jest przykład\n wymuszenia łamania linii. Odpowiadaza to znak \\n.*/




Wybrane sposoby zmiany stylu czcionki — pismo pochyłe

/*!...

To jest przykład wymuszenia \e pisma \e pochyłego.Odpowiada za to polecenie \\e.*/




Wybrane zmiany stylu czcionki — pismo maszynowe

/*!...

To jest przykład \p pisma \p maszynowego.Odpowiada za to polecenie \\p.*/




Linia polecenia

Dokumentację można wygenerować wywołującz linii polecenia program doxygen. W wywoła-niu tym jako parametru należy użyć pliku (wrazze ś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




Linia polecenia

Lepszym jednak pomysłem jest stworzenie odpowied-niego pliku Makefile. Pozwala to przekierować wyj-ście standard error do pliku. Dzięki temu późnejmożna przeglądać wszystkie ostrzeżenia i komunikatybez komunikatów informacyjnych generowanych przezprogram doxygen.

Konsola:

jkowalsk@panamint> make




Przykładowa minimalna zawartość pliku Makefile

Makefilestart doxy :

doxygen Doxyfile 2> doxy.logless doxy.log



Koniec prezentacjiDziękuję za uwagę


Doxygen system generowania dokumentacjikreczmer/kpo/materialy/dodatki/...Programowanie obiektowe...

Documents

Transcript of Doxygen system generowania dokumentacjikreczmer/kpo/materialy/dodatki/...Programowanie obiektowe...