Generatory dokumentacji kodu źródłowego

Prezentacja na temat: "Generatory dokumentacji kodu źródłowego"— Zapis prezentacji:

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

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
/** * <p>Tekst dokumentacji</p> */ Większość generatorów dopuszcza umieszczanie w DocBlock’ach niektórych tagów HTML, czasem innych (np. LaTeX)

10 Tagi /** * Jakaś funkcja. 10.5 */ function bla(){} @identyfikator – nieobowiązkowy element DocBlock’u, 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 - wstawienie linku @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! –1.33(3) ;-) balon */ class hello extends bazowa{ /// Konsturktor function hello(){} * Wypisuje tekst. void function pisz(){} }

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

14 Porównanie narzędzi dla PHP
phpdoc.org Phpxref phpdoc.de phpdoc+ JavaDoc phpDocGen BalonDoc Język PHP Perl Java styl JavaDoc + ~ niezależność od struktury plików - dokumentacja generowane formaty HTML, PDF, CHM, XML HTML „Doclety” HTML, LaTex interfejs linia poleceń, docBuilder linia 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.<br> * ***********************/

17 Inne języki (narzędzia darmowe)
JavaDoc – część SDK DOC++ Doxygen CppDoc I wiele innych – długa lista jest na stronie: