Dokumentacja i systemy jako±ci

Dokumentacja i systemy jako±ci Generatory dokumentacji Iwona Kocha«ska KSEM WETI PG January 15, 2016

Dokumentacji oprogramowania - po co? Po co? Dokumentacja bibliotek, pakietów, moduªów, klas, procedur, by mogªy by u»ywane przez osoby inne ni» autor Dokumentacja dla autora, który mo»e zapomnie, o co mu chodziªo Dokumentacja oprogramowania udost pnianego publicznie Dokumentacja oprogramowania: techniczna (przez programistów dla programistów) administracyjna u»ytkownika

Dokumentacji oprogramowania - po co? Informatyk nie cierpi pisania dokumentacji problemy z wypowiadaniem si na pi±mie, poczucie straty czasu, trudno± w stosowaniu procedur i standardów konieczno± aktualizowania dokumentacji Je±li dokumentacja kodu ma by pisana na bie» co i poprawiana gdy kod si zmienia - musi by automatycznie budowana na jego podstawie Je±li jaka± informacja jest zapisana w dwóch ró»nych miejscach, w jednym z nich wcze±niej lub pó¹niej b dzie nieaktualna. A kod jest zawsze aktualny Aktualnie u»ywane j zyki programowania nie dokumentuj si same

Dokumentacji oprogramowania - po co? Potrzebny jest specyczny format komentarzy oraz.. Narz dzie, które automatycznie wygeneruje dokumentacj z tak obkomentowanego kodu Wygenerowana dokumentacja powinna by ªatwo dost pna: przystepny format - mo»liwo± szybkiego i wygodnego dost pu z dowolnego miejsca (np. HTML) dobry indeks - ogólna lista wygenerowana wraz z szczegóªowymi dokumentami lub wyszukiwarka dobrze znane miejsce - mo»liwo± traenia do aktualnej wersji dokumentu przy pomocy paru ruchów myszki Wersje papierowe szybko si dezaktualizuj.

Dokumentacji oprogramowania - po co? Metryczka: Co to za wersja? Numer, data ostatniej zmiany - od±wie»ane automatycznie! Co si ostatnio zmieniªo? - historia zmian wygenerowana z repozytorium kodu na bazie komentarzy podawanych przy zatwierdzaniu zmian Gdzie i w jaki sposób nale»y zadawa pytania oraz zgªasza bª dy i w tpliwo±ci? Dokumentacja API nie jest peªn dokumentacj biblioteki lub programu Biblioteka - podr cznik u»ytkownika (w stylu samouczkowym) oraz zestaw dziaªaj cych przykªadów Zªo»ony program - dokument projektowy zawieraj cy opis: celu, kluczowych wymaga«, podstawowych zaªo»e«przyj tych w implementacji, list najwa»niejszych funkcji, klas i obiektów kilka diagramów obrazuj cych najwa»niejsze interakcje

Narz dzia Donald E. Knuth - koncepcja ª czenia kodu z dokumentacj pierwsza wersja systemu T EX literate programming - pliki ¹ródªowe, w których bloki kilkunastu wierszy kodu przeplataªy si z podobnej wielko±ci fragmentami dokumentacji; jedno narz dzie wycinaªo z pliku ¹ródªowego w celu kompilacji a inne wydzielaªo dokumentacj Python - sformatowane komentarze dokumentacyjne (zamieszczane na pocz tku klasy/funkcji) s dost pne dla kodu programu, wraz z metaopisem klas i funkcji; Narz dzia do generowania dokumentacji. Java - JavaDoc prosty format komentarzy dokumentacyjnych standard powielany przez generatory dla C++

Narz dzia J zyk C++ kdoc doc++ doxygen Wszystkie narz dzia obsªuguj generowanie HTML, niektóre tak»e inne formaty (TEX, RTF). Wszystkie narz dzia generuj hierarchie klas, opisy klas, metod, atrybutów i funkcji (nawet pod nieobecno± komentarza dokumentacyjnego w kodzie)

Zastosowanie w projektowaniu Zalety dokumentacji kodu: wymusza przemy±lenie architektury programu wymusza zdeniowanie podstawowych poj pozwala na wyªapanie niedoskonaªo±ci projektowych przed rozpocz ciem kodowania korygowanie API i komentarzy boli mniej ni» wyrzucanie sporych gotowych fragmentów kodu

Doxygen Autor projektu: Dimitri van Heesch Strona projektu: http://www.doxygen.org Doxygen jest systemem dokumentowania oprogramowania pisanego w C++, C, Java, Objective-C, Python, IDL, Fortran, VHDL, PHP, C#. System mo»e generowa : dokumentacj w HTML ¹ródªa dla LaTex'a

Doxygen Dokumentacja mo»e mie format: RTF (MS-Word), PostScript, PDF HTML stron podr cznika w systemie UNIX dla programu man. Dokumentacja mo»e by generowana: bezpo±rednio ze ¹ródeª z plików stowarzyszonych z nimi. Doxygen jest programem tworzonym dla systemu Linux i Mac OS w oparciu o bibliotek Qt ( doxywizard ). oprogramowanie przeno±ne. uruchomiane pod systemem UNIX i jego klonami. dost pne równie» w postaci binarnej dla systemu MS Windows

Doxygen Najbardziej znane projekty wykorzystuj ce Doxygen: Adobe Open Source strona domowa projektów ASL (Adobe Source Libraries) KDE - dokumentacja ró»nych bibliotek Samba OSCAR (http://www.oscar-net.org) - dla systemów robotycznych XEngine (http://xengine.sourceforge.net) - silnik dla wizualizacji 3D w czasie rzeczywistym Xerces C++ Parser biblioteka umo»liwiaj ca pisanie aplikacji z parserem XML

Komponenty Doxygen doxygen - generowanie dokumentacji na podstawie utworzonego wcze±niej pliku konguracyjnego i ¹ródeª programów 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 - graczna aplikacja uªatwiaj ca tworzenie pliku konguracyjnego dla dokumentacji danego projektu. graphviz - tworzenie rysunków grafów (http://www.research.att.com/sw/tools/graphviz)

Doxygen - przepªyw informacji

Doxywizard - opcje podstawowe Wybór punkt uruchamienia Doxywizard (np. katalog dox)

Doxywizard - opcje podstawowe

Doxywizard - opcje rozszerzone

Doxywizard - opcje rozszerzone Dot - narz dzie do generowania diagramów (pakiet GraphViz)

Doxywizard - uruchamianie generatora dokumentacji

Przykªadowa dokumentacja

Doxygen - uruchamianie z linii polece«utworzenie pliku konguracji: doxygen - g [nazwa pliku] (nazwa pliku jest opcjonalna domy±lnie jest tworzony plik o nazwie Doxyle ). Edycja pliku konguracji Generowanie dokumentacji: doxygen [nazwa pliku] Za pomoc Makele - mo»na przekierowa wyj±cie standard errorn do pliku. Konsola: make Zawarto± pliku Makele: start_doxy : doxygen Doxyle 2> doxy.log less doxy.log

Formaty komentarzy

Formaty komentarzy - polecenia Wewn trz komentarzy mo»na umieszcza specjalne polecenia (zaczynaj ce si od znaku \ l ub @ po którym nast puje nazwa polecenia)

Formaty komentarzy - listy

Literatura http://mekk.waw.pl/mk/narzedzia/narzedzia_gendoc http://icis.pcz.pl/~agrosser/test/doxygen.pdf http://rab.ict.pwr.wroc.pl/~kreczmer/po/materialy/11-doxygen.pdf