Dokumentowanie kodu
Kurs programowania 1
Program
Java - wykład 6
Java jest wyposażona w generator dokumentacji który na podstawie
odpowiednio napisanych komentarzy w kodzie programu (które
jednak nie są konieczne), generuje dokumentację w HTML-u.
Maciek Gębala
Sposób generowania komentarzy do dokumentacji jest zgodny z
większością standardów przestrzeganych również przez inne
18 grudnia 2010 generatory dokumentacji.
Maciek Gębala Kurs programowania 1 Maciek Gębala Kurs programowania 1
Najważniejsze opcje Składnia dokumentowania
 czytaj ogólną dokumentację z pliku html
 wyświetl tylko publiczne klasy
 wyświetl wszystko co nie jest prywatne
Komentarz dokumentujący
 wyświetl wszystko
Umieszczany zazwyczaj przed dokumentowanym obiektem (klasą,
 ustawia kodowanie pliku wejściowego funkcją, ...).
 katalog docelowy
 dodaje paragrafy z dyrektywą
Pierwszy znak w kolejnych wierszach jest pomijany.
 dodaje paragrafy z dyrektywą
 dodaje tytuł domyślny stron
Wewnątrz takiego komentarza mogą pojawić się bezpośrednio
również znaczniki HTML-a które będą przepisane do wynikowego
 dodaje nagłówek stron
pliku dokumentacji. Jednak jak wskazuje praktyka lepiej tego unikać,
 dodaje stopkę stron
szczególnie jeśli chcielibyśmy użyć innego generatora dokumentacji.
 dodaje tekst na górze stron
 dodaje tekst na dole stron
 nie generuj hierarchii klas
 nie generuj indeksu
Maciek Gębala Kurs programowania 1 Maciek Gębala Kurs programowania 1
Wybrane dyrektywy dokumentacyjne Wybrane dyrektywy dokumentacyjne
Odwołanie się do innych miejsc w dokumentacji (system
Opisuje parametry używane przez metody i ma postać:
automatycznie tworzy odwołanie).
Opis kończy się w momencie wystąpienia innej dyrektywy lub końca
komentarza.
Opisuje wynik zwracany przez metodę i ma postać:
Pozwala na umieszczenie odnośnika w innym miejscu niż sekcja See
Also.
Opis kończy się w momencie wystąpienia innej dyrektywy lub końca
komentarza.
Po dyrektywie umieszczamy informacje istotne dla wersji.
Opisuje wyjątki generowane przez metodę i ma postać:
Opis kończy się w momencie wystąpienia innej dyrektywy lub końca
Informacje o autorze. Wyświetlane jeśli generowanie jest z
komentarza.
parametrem .
Maciek Gębala Kurs programowania 1 Maciek Gębala Kurs programowania 1
Wybrane dyrektywy dokumentacyjne Alternatywne generatory dokumentacji
Doxygen
System generowania dokumentacji przystosowany do większości
stosowanych języków programowania, zwracający dokumentację w
Sugeruje aby nie używać danej metody gdyż w przyszłości może
wielu formatach (html, latex -> pdf, rtf, man, ...).
zostać usunięta.
Przykład użycia dla plików i .
Maciek Gębala Kurs programowania 1 Maciek Gębala Kurs programowania 1
JAR
Narzędzie do zapakowania wszystkich klas w jeden plik. Działa na
podstawie kompresji . Zawiera plik w katalogu
który może opisywać pewne własności aplikacji.
Przykład pliku
Użycie:
-c  utwórz nowe archiwum
-t  wyświetl zawartość archiwum
-u  odśwież zawartość archiwum
-x  rozpakuj archiwum
-f jar-file  nazwa archiwum
-m manifest  dodaj podany manifest
Maciek Gębala Kurs programowania 1