Pobieranie prezentacji. Proszę czekać

Pobieranie prezentacji. Proszę czekać

Cel tworzenia dokumentacji Sposób dokumentowania Przegląd narzędzi Generatory dokumentacji kodu źródłowego.

Podobne prezentacje


Prezentacja na temat: "Cel tworzenia dokumentacji Sposób dokumentowania Przegląd narzędzi Generatory dokumentacji kodu źródłowego."— Zapis prezentacji:

1 Cel tworzenia dokumentacji Sposób dokumentowania Przegląd narzędzi Generatory dokumentacji kodu źródłowego

2 Po co dokumentować kod? Prezentacja interfejsu Duże projekty, współpraca wielu programistów, łatwa kontrola Wielokrotne wykorzystanie tego samego kodu Pomoc w wykrywaniu błędów w projekcie

3 Komentarze w kodzie Informacja będąca w dwóch miejscach – z czasem będzie nieaktualna Informację w kodzie źródłowym łatwiej utrzymać jako aktualną Programiście łatwiej czytać (i umieszczać) komentarze w kodzie Generator dokumentacji przetwarza ją na bardziej czytelny format dla innych

4 Rodzaje dokumentacji Generowana na żądanie klienta Statyczna – generowana co jakiś czas Dostępna przez sieć (np. w formacie HTML) W formacie do druku (np. ps, pdf) Opisująca tylko strukturę (XML)

5 Działanie generatora Wejście – kod źródłowy z odpowiednio sformatowanymi komentarzami (ew. bez komentarzy) Wyjście – gotowa dokumentacja w odpowiednim formacie (formatach)

6 Budowa generatora Podział na: Front-end (przód) Back-end (tył) Doclets Rozne formaty, rozne jezyki

7 Komentarze typu JavaDoc /** * Tekst dokumentacji. */ /// Jednowierszowy Używane przez większość generatorów Odnoszą się do najbliższego następnego elementu

8 /** * Przykładowa klasa. * Pozwala wypisać Hello, world! */ class hello{ /** * Konstruktor */ function hello(){} /** * Metoda wypisująca tekst Hello, world! */ function wypisz(){ echo Hello, world!;} }

9 Formatowanie wizualne /** * Tekst dokumentacji */ Większość generatorów dopuszcza umieszczanie w DocBlockach niektórych tagów HTML, czasem innych (np. LaTeX)

10 Tagi /** * Jakaś funkcja. * @version 10.5 */ function bla(){} @identyfikator – nieobowiązkowy element DocBlocku, przypisujący danemu atrybutowi wartość generatory mają listy rozpoznawanych tagów

11 Przykładowe tagi @version - wersja @author – kto jest autorem @param – opis parametrów funkcji @return – opis wartości zwracanej przez funkcje @see – link do dokumentacji innego elementu @link http://www.phpdoc.org - wstawienie linkuhttp://www.phpdoc.org @source – wstawienie kodu źródłowego funkcji @package – pakiet do którego należy dany element @abstract – określenie klasy abstrakcyjnej @access [public | private]

12 /** * Przykładowa klasa. * Pozwala wypisać Hello, world! * @link http://www.phpdoc.orghttp://www.phpdoc.org * @version –1.33(3) ;-) * @author balon * @abstract */ class hello extends bazowa{ /// Konsturktor function hello(){} /** * Wypisuje tekst. * @return void */ function pisz(){} }

13 Narzędzia dla PHP phpDocumentor (www.phpdoc.org)www.phpdoc.org phpxref (phpxref.sourceforge.net)phpxref.sourceforge.net PHPDoc (www.phpdoc.de)www.phpdoc.de PHPDoc nakładka na JavaDoca (www.callowayprints.com/phpdoc)www.callowayprints.com/phpdoc PHPDocGen – napisany w perlu PHPAutoDoc PHPCodeDoc BalonDoc ;-) – dokumentacja SSUL

14 Porównanie narzędzi dla PHP phpdoc.orgPhpxrefphpdoc.dephpdoc+ JavaDoc phpDoc Gen BalonDoc JęzykPHPPerlPHPJavaPerlPHP styl JavaDoc+++++~ niezależność od struktury plików ++--++ dokumentacja+--++- generowane formaty HTML, PDF, CHM, XML HTML DocletyHTML, LaTex HTML interfejslinia poleceń, docBuilder linia poleceń skrypt phplinia poleceń skrypt php sygnalizacja błędów +----validator

15 BalonDoc ;-) (1) Stworzony na potrzeby serwera SSUL Wypluwa tylko HTML, ale podzielony na Front-end i Back-end Generuje dokumentacje na żądanie – zawsze aktualną Używa swojego parsera Można mieszać kod obiektowy i strukturalny, niezależny od struktury plików Brak komentarzy mu nie przeszkadza, ale nadmiarowe komentarze stwarzają problemy

16 BalonDoc ;-) (2) Komentarze: /********************* * NazwaKlasy * ********************* * Opis działania * * klasy. * ********************* * autor wersja * *********************/ /*********************** * Opis\n funkcji. * ***********************/

17 Inne języki (narzędzia darmowe) JavaDoc – część SDK DOC++ Doxygen CppDoc I wiele innych – długa lista jest na stronie: http://www.stack.nl/~dimitri/doxygen/links.html http://www.stack.nl/~dimitri/doxygen/links.html


Pobierz ppt "Cel tworzenia dokumentacji Sposób dokumentowania Przegląd narzędzi Generatory dokumentacji kodu źródłowego."

Podobne prezentacje


Reklamy Google