Generatory dokumentacji kodu źródłowego

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. * @version 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 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]

12. /** * 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(){} }

13. 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

14. Porównanie narzędzi dla PHP

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: http://www.stack.nl/~dimitri/doxygen/links.html