Javadoc jest narzędziem ułatwiającym pisanie dokumentacji technicznej projektu. Przetwarza ono specjalne komentarze umieszczone w kodzie na strony www, automatycznie dołączając informacje o nazwach komentowanych klas, metod itd.
Komentarze, które mają zostać przetworzone przez javadoc muszą zaczynać się znakami: /**, a kończyć */. W komentarzu możemy umieścić dowolny kod html, który zostanie bez zmian przeniesiony do wygenerowanej dokumentacji. Dodatkowo, javadoc rozpoznaje znaczniki dokumentacyjne, rozpoczynające się od znaku @.
Komentować możemy klasy, metody oraz zmienne. W najprostszym przypadku wygląda to następująco:
/** Komentarz dla klasy */
public class Klasa {
/** Komentarz dla metody */
public int Metoda() { return -13; }
/** Komentarz dla zmiennej */
protected String napis;
}
Domyślnie, javadoc przetwarza jedynie składowe publiczne i chronione, ponieważ tylko te składowe są istotne z punktu widzenia użytkownika klasy. Można jednak dołączyć dokumentację dla składowych pakietowych i prywatnych dodając odpowiednią opcję przy uruchamianiu programu javadoc.
Najlepszym przykładem wykorzystania javadoc-a jest dokumentacja biblioteki javy: http://java.sun.com/j2se/1.5.0/docs/api/.
Komentarze można dodać również do pakietów. W tym celu należy stworzyć plik package-info.java w katalogu odpowiadającym paczce, i umieścić w nim komentarz wraz z deklaracją paczki:
/** Komentarz dla paczki */
package moja.paczka;
Można też dodać informację o całej aplikacji (zestawie pakietów), która będzie włączona do dokumentacji - jest to strona pojawiająca się gdy otwieramy stronę główną dokumentacji. Aby to zrobić, należy utworzyć stronę html (na ogół overview.html) i podać ścieżkę do tego pliku przy uruchomieniu programu javadoc po opcji -overview.
| Znacznik | Opis |
|---|---|
| @author autor | Informacja o autorze (może być wielu). |
| @version wersja | Informacja o wersji. |
| @see klasa lub klasa#metoda lub napis | Generuje odwołanie do dokumentacji innej klasy, metody lub informację o odwołaniu. |
| {@link klasa#metoda etykieta} | Działa tak samo jak @see, z tym że może być stosowany wewnątrz wiersza. Zamiast słów "See also" umieszczany jest napis etykieta. |
| @deprecated | Oznacza składowe, które zostały zastąpione przez nowsze wersje i używanie ich nie jest zalecane. |
| {@docRoot} | Generuje względną ścieżkę do głównego katalogu zawierającego dokumentację. |
| {@inheritDoc} | Umieszcza w bieżącym komentarzu dokumentację najbliższej klasy bazowej aktualnie dokumentowanej klasy. |
| Znacznik | Opis |
|---|---|
| @param parametr opis | Opisuje jeden parametr metody. Może ich być dowolnie dużo, jednak na ogół jest ich tyle ile parametrów metody, w takim samym porządku. |
| @return opis | Opisuje wartość zwracaną przez metodę. |
| @throws wyjątek opis (albo @exception wyjątek opis) | Opisuje wyjątek, który może być rzucony przez tę metodę. |
Wyświetlenie instrukcji obsługi javadoc ze wszystkimi opcjami:
javadoc
lub
javadoc -help
Generowanie dokumentacji:
javadoc [opcje] nazwa_pakietu
lub
javadoc [opcje] nazwa_pliku.java
Uwaga: nazwy mogą zawierać znaki wieloznaczne (czyli np. *.java).
Wybrane opcje:
Jeśli nie została określona opcja –doclet wiersza poleceń javadoc’a, to używany jest standardowy doclet.
Wybrane opcje dostarczane przez standardowy doclet:
Dokumentacja jest zorganizowana w sposób czytelny i intuicyjny, gdyby jednak pojawiły się problemy w zrozumieniu tej struktury, można znaleźć jej opis na stronie Help.
Eclipse bardzo ułatwia korzystanie z javadoc-u. Przede wszystkim można w łatwy sposób wygnerować szkielet komentarza, należy:
Ułatwione jest także generowanie dokumentacji. Aby to zrobić, należy z menu Project wybrać pozycję Generate Javadoc.... Na kolejnych formularzach możemy okreslić dla których pakietów/ klas chcemy wygenerować dokumentację, gdzie ją zapisać, które tagi uwzględnić i wiele innych opcji.
Doclety są klasami Javy, przetwarzającymi plik źródłowy programu. Na ogół korzysta się z standardowego docletu, który generuje stronę www. Można napisać własny doclet, który może mieć zupełnie inną funkcję niż generowanie dokumentacji: mamy do dyspozycji obiekt, zawierający informacje o wszystkich klasach, metodach, zmiennych, wraz z ich komentarzami i zasięgami widoczności. Doclet można podmienić przez zastosowanie odpowiedniej opcji programu javadoc. Przykłady i dokumentacja API docletów znajduje się na stronie http://java.sun.com/j2se/1.5.0/docs/guide/javadoc/doclet/overview.html.