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

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

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

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)

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

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

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

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

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

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

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 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]

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

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

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

„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

„BalonDoc” ;-) (2) Komentarze: /********************* * NazwaKlasy * * Opis działania * * klasy. * * autor wersja * *********************/ /*********************** * Opis\n funkcji.<br> * ***********************/

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