Zasady Programowania (Projektowanie) – C++

Transkrypt

Zasady Programowania (Projektowanie) – C++ - część 3
1/17
Doxygen - wprowadzenie
Zasady Programowania (Projektowanie)
C++ – część 3
Temat: Doxygen - wprowadzenie
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: www.doxygen.org
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
Przygotował: mgr inż. Jakub Filip Możaryn
2007-03-05
e-mail: [email protected], WWW: http://grafit.mchtr.pw.edu.pl/~mozaryn
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).
2007-03-05
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.
2007-03-05
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.
2007-03-05
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)
2007-03-05
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.
2007-03-05
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
wygenerowanie dokumentacji do kodu, w którym nie ma
umieszczonych specjalnych komentarzy.
OUTPUT_DIRECTORY
określa ścieżkę do katalogu wyjściowego. Domyślnie
dokumentacja tworzona jest w katalogu bieżącym.
INPUT
określa pliki i katalogi, które mają być przeanalizowane
przez Doxygena. Gdy nie jest ustawiony, brane są pliki z
bieżącego katalogu.
FILE_PATTERNS -
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.
2007-03-05
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 {
...
}
2007-03-05
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
oznacza, że dokumentowana będzie klasa
\struct
oznacza, że dokumentowana będzie struktura
\union
oznacza, że dokumentowana będzie unia
\enum
oznacza, że dokumentowane będzie wyliczenie
\fn
oznacza że dokumentowana będzie funkcja
\var
dokumentowana będzie zmienna, wyliczenie lub
definicja typu
\def
dokumentowane będzie makro
\file
dokumentowany będzie plik
\namespace
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
2007-03-05
10/17
Inne komendy doxygena:
\attention tekst
tworzy sekcje Uwaga (ang. Attention) i umieszcza w niej
tekst
\author lista autorów
dodaje sekcje Autor
\date data
dodaje sekcję daty
\warning
dodaje sekcje ostrzeżenień
\bug tekst
dodaje sekcję błędów
\note tekst
dodaje sekcje notatek
\par nazwa_sekcji
dodaje sekcje o podanej nazwie, w następnej linii
zaczyna się tekst do tej sekcji
\return tekst
opis wartości zwracanych
\retval wartość opis
opis wartości zwracanej
\since tekst
pozwala określić od kiedy dana funkcja/klasa jest
dostępna
\todo tekst
dodaje sekcje todo
\version nr_wersji
dodaje numer wersji
\b słowo
pogrubia wpisane słowo
\c słowo
zapisuje podane słowo za pomocą czcionki regularnej
\code
rozpoczyna blok kodu źródłowego
\endcode
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 zapisać znak \
\@
pozwala zapisać znak @
\&
pozwala zapisać znak & w HTML-u
\$
pozwala zapisać znak $
pozwala utworzyć prostą listę
2007-03-05
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.
*/
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.
\see int funkcja2()
*/
W dokumentacji mozliwe jest też automatyczne generowanie odpowiednio opisanych
wzorów matematycznych.
2007-03-05
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 1  y  f 2  x
w p.p.
(1)
f 1 a =e a ∑ i=1 sinia , c=rand 2,3 , ...,5
(2)
F  x , y ={
−a
f 1  y f 2  x 
f  x f 1  f 2  y 
2
1
10
c
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
argument x funkcji f3(x,y)
argument y funkcji f3(x,y)
\return
*/
wynik działania funkcji f3(x,y)
double f3(int x, int y);
{ten komentarz nie pojawi się w dokumentacji}
//obliczanie wartosci funkcji f3
2007-03-05
13/17
Dokumentowanie pliku
/*!
\file Unit2.cpp
\brief plik zawierający funkcje matematyczne wykorzystywane w programie
*/
2007-03-05
14/17
6. Dodatek A
Podstawowe opcje konfiguracyjne
Opis najważniejszych opcji podstawowych:
PROJECT_NAME
nazwa projektu
PROJECT_NUMBER
wersja projektu
OUTPUT_DIRECTORY
katalog wyjściowy dla dokumentacji (katalog, w którym zostanie
zapisana dokumentacja)
OUTPUT_LANGUAGE
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
EXTRACT_ALL
określa czy mają być w dokumentacji nazwy klas funkcji i
zmiennych, które nie posiadają opisu w kodzie źródłowym
EXTRACT_PRIVATE
określa czy mają być dokumentowane prywatne składowe klas
EXTRACT_STATIC
określa czy mają być dokumentowane statyczne składowe klas
HIDE_UNDOC_MEMBERS
określa czy na różnych podsumowaniach/indeksach mają być
widoczne nie udokumentowane składowe
HIDE_UNDOC_CLASSES
określa czy na różnych podsumowaniach/indeksach mają być
widoczne nie udokumentowane klasy
BRIEF_MEMBER_DESC
określa czy ogólne opisy składowych mają znajdować się w opisie
(indeksie) klasy
REPEAT_BRIEF
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
ALWAYS_DETAILED_SEC
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
FULL_PATH_NAMES
określa czy nazwy plików mają być poprzedzane ścieżką dostępu
(dotyczy także nazw plików nagłówkowych)
STRIP_FROM_PATH
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
CLASS_DIAGRAMS
określa czy doxygen ma generować diagram przedstawiający
dziedziczenie pomiędzy klasami (HTML i LaTeX)
SOURCE_BROWSER
określa czy należy generować listę plików źródłowych w
dokumentacji
INLINE_SOURCES
określa czy dodawać kod źródłowy funkcji i klas do dokumentacji
STRIP_CODE_COMMENTS
określa czy mają być ukryte komentarze w kodach źródłowych
dodawanych do dokumentacji
CASE_SENSE_NAMES
określa czy nazwy plików są wrażliwe na wielkość liter
SHORT_NAMES
określa czy pliki dokumentacji mają mieć krótkie nazwy
2007-03-05
15/17
HIDE_SCOPE_NAMES
określa czy przy nazwach funkcji zapisywać nazwę klasy i o
przestrzeni nazw, do której należy funkcja
VERBATIM_HEADERS
określa czy doxygen do dokumentacji każdej klasy ma dodawać
dokładną kopię pliku nagłówkowego, w którym jest zadeklarowana
SHOW_INCLUDE_FILES
określa czy należy dodawać listę plików nagłówkowych dodawanych
przez dokumentowany plik
JAVADOC_AUTOBRIEF
określa czy doxygen ma interpretować ogólne opisy w stylu JavaDoc
INHERIT_DOCS
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
INLINE_INFO
określa czy przed składowymi typu inline należy umieszczać tekst
[inline]
SORT_MEMBER_DOCS
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
DISTRIBUTE_GROUP_DOC czy należy użyć opisów pierwszej zgrupowanej składowej dla całej
grupy
TAB_SIZE
rozmiar tabulatora
ENABLED_SECTIONS
włącza i wyłącza sekcje dokumentacji
GENERATE_TODOLIST
określa czy generować listę todo (komenda \todo)
GENERATE_TESTLIST
określa czy generować listę testów (komenda \test)
GENERATE_BUGLIST
określa czy generować listę błędów (komenda \bug)
OPTIMIZE_OUTPUT_FOR_
określa czy optymalizować dokumentacje dla C
C
SHOW_USED_FILES
określa czy dodawać listę plików, która została użyta do
generowania dokumentacji
Opcje dotyczące procesu generowania dokumentacji:
QUIET
włącza / wyłącza komunikaty doxygena
WARNINGS
włącza / wyłącza wyświetlanie komunikatów z ostrzeżeniami
WARN_IF_UNDOCUMENTE określa czy wyświetlać komunikat z ostrzeżeniem jeżeli doxygen
D
napotka nieudokumentowaną składową
WARN_FORMAT
pozwala określić format ostrzeżeń
WARN_LOGFILE
pozwala określić plik do którego doxygen będzie zapisywał
komunikaty o błędach
Opcje dotyczące plików wejściowych:
INPUT
pliki źródłowe na podstawie, których należy generować
dokumentacje (można także podać katalog), separatorem jest spacja
FILE_PATTERNS
pozwala filtrować pliki za pomocą wyrażeń regularnych np: *.cpp
RECURSIVE
czy należy włączać do dokumentowania pliki z podkatalogów
EXCLUDE
pozwala określić pliki lub katalogi które należy pominąć przy
2007-03-05
16/17
generowaniu dokumentacji
EXCLUDE_PATTERNS
pozwala filtrować pliki które należy pominąć za pomocą wyrażeń
regularnych np.: *.o
EXAMPLE_PATH
pozwala określić pliki lub katalogi, które zawierają przykładowe
fragmenty kodu dodawane do dokumentacji za pomocą komendy
\include
EXAMPLE_PATTERNS
jeżeli EXAMPLE_PATH zawiera katalogi można użyć
EXAMPLE_PATTERNS do określenia plików
IMAGE_PATH
ścieżka dostępu do plików graficznych które następnie mozna dodać
do dokumentacji za pomocą komendy \image
INPUT_FILTER
pozwala określić program filtrujący, który przefiltruje każdy plik
wejściowy przed rozpoczęciem generowania dokumentacji
FILTER_SOURCE_FILES
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
określa czy doxygen ma tworzyć alfabetyczny indeks klas, struktur
itd.
COLS_IN_ALPHA_INDEX
pozwala określić liczbę kolumn w alfabetycznym indeksie klas,
struktur
IGNORE_PREFIX
pozwala określić prefiks, który ma być ignorowany przy tworzeniu
alfabetycznego indeksu
Opcje dotyczące dokumentacji generowanej w postaci HTML-u:
GENERATE_HTML
określa czy generować dokumentacje w postaci HTML
HTML_OUTPUT
pozwala określić katalog, w którym ma zostać wygenerowana
dokumentacja w postaci HTML-u
HTML_HEADER
pozwala określić nagłówek HTML, jeżeli nie ustawione doxygen
wygeneruje własny
HTML_FOOTER
pozwala określić stopkę dla generowanej dokumentacji, jeżeli nie
określone doxygen wygeneruje standardową stopkę
HTML_STYLESHEET
pozwala określić plik styli css, które ma wykorzystywać
dokumentacja
HTML_ALIGN_MEMBERS
określa czy położenie składowych ma być określane za pomocą
tabeli (YES) czy wypunktowania (NO)
DISABLE_INDEX
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
2007-03-05
17/17
LaTeXie
Najważniejsze opcje preprocesora w doxygen:
ENABLE_PREPROCESSING
określa czy doxygen ma przetwarzać dyrektywy preprocesora
znalezione w dokumentowanym kodzie
MACRO_EXPANSION
określa czy doxygen ma przetwarzać makra preprocesora
2007-03-05

Zasady Programowania (Projektowanie) – C++

Transkrypt

Podobne dokumenty

Generowanie dokumentacji w doxygen

Liczba stypendiów: 5 Instytucja oferująca stypendium (zakład

Liczba stypendiów: 3 Instytucja oferująca stypendium (zakład

Oprogramowanie i wykorzystanie stacji roboczych Wykład 2

Doxygen

Programowania Grafiki Komputerowej (projekt) (zasady zaliczania)

regulamin - Wydział Inżynierii Chemicznej i Procesowej

MEDAL BRĄZOWY ZA DŁUGOLETNIĄ SŁUŻBĘ 1. mgr

Programista