Komentarze są częścią tekstu opisującego kawałki programu Javy. W Javie możemy stosować komentarze jednej linii. Komentarz dla pojedynczej linii rozpoczyna się //. Przykład:
// Pojedyncza linia komentarza programu Javy
Mamy także możliwość komentowania wielu linii programu, podobnie jak w języku C i C++, na początku bloku /* i kończymy blok komentarza znakami */, na przykład:
/* Blok tekstu komentarza w Javie w kilku liniach */
Java wprowadza także dodatkowy rodzaj komentarzy nazywanych komentarzami dokumentującymi. Służą one do pomocy w automatycznym generowaniu dokumentacji programisty i do zapewnienia spójności między dokumentacją i kodem programu. Do automatycznej generacji dokumentacji służy program javadoc.exe, który generuje na podstawie komentarzy dokumentujących plików źródłowych Javy pliki w formacie HTML. Dla każdej klasy publicznej lub interfejsu, javadoc tworzy strony HTML składające się z następujących składników:
Komentarze dokumentujące mają następującą formę:
/**komentarz dokumentujący*/.
To czy komentarz jest używany przez javadoc do tworzenia dokumentacji, zależy od kontekstu. Komentarze dokumentujące są znaczące dla Javy tylko w następujących okolicznościach:
Pierwsza linia każdego komentarza dokumentującego ma szczególne znaczenie. Jest używana jako ogólny opis klasy, metody lub pola danych i jest wstawiana jako jednolinijkowe streszczenie we właściwym indeksie (patrz wyżej: składniki 4-6). Zdanie to zakończone może być wcześniej kropką.
Za liniami z ogólnym opisem występują linie zawierające normalny tekst. Linie te zawierają szczegółowe wyjaśnienie, rozszerzające informacje zawarte w linii ogólnego opisu. Ich wystąpienie nie jest obowiązkowe. Tekst w tych liniach komentarza dokumentującego może zawierać znaczniki języka HTML (służące do formatowania dokumentu) z wyjątkiem znaczników: <H1>, <H2>, <H3>, <H4>, <H5>, <H6>, oraz <HR>,które zarezerwowane są dla generatora dokumentacji i nie powinny być używane w tekście komentarzy dokumentujących.
W zależności od kontekstu, komentarze dokumentujące mogą zwierać dodatkowe słowa kluczowe tzw. znaczniki, te wyróżnione komponenty są specjalnie traktowane. Wszystkie znaczniki rozpoczynają się symbolem @, i powinny być na początku linii w której się pojawiają. Jakiekolwiek spacje wiodące, po których występuje gwiazdka ( * ), są ignorowane, tak więc sekwencja *@znacznik jest rozpoznawana jako znacznik. Linie ze znacznikami powinny pojawiać się zawsze za liniami opisu.
Znaczniki komentarzy dokumentujących:
ZNACZNIK: | PRZYKŁAD: |
znaczniki definicji klasy;
@see nazwa-klasy |
@see MojaKlasa |
@see nazwa-klasy#metoda |
@see MojaKlasai#mojaFunkcja |
@see kwalifkowana-nazwa-klasy |
@see MojPakiet.MojaKlasa |
@see kwalifkowana-nazwa-klasy#metoda |
@see MojPakiet.MojaKlasa#mojaFunkcja |
@version dowolny-tekst |
@version 2.01 |
@author dowolny-tekst |
@author Artur Tyloch |
znaczniki definicji zmiennych;
@see (dowolny z powyższych znaczników) |
znaczniki definicji metod;
@see (dowolny z powyższych znaczników) |
|
@return dowolny-tekst |
@return Lokalną datę |
@param nazwa-parametru dowolny-tekst |
@param n Liczba szukanych książek |
@exception nazwa-klasy-obsługi-wyjątku dowolny-tekst |
@exception MojWyjatek dzielenie liczby przez 0 |
Tabela 2-12 Znaczniki komentarzy dokumentujących.
Linie zawierające znaczniki nie są sortowane według typów znaczników, tak więc należy zadbać aby wszystkie linie znaczników tego samego typu znajdowały się razem. np. linie znaczników @param razem i tak samo dla znaczników @exception i innych.
Poniżej przedstawiam dwa możliwe style
formatu dla komentarzy dokumentujących:
/** Linia z ogólnym opisem klasy, metody lub pola danych. Ewentualne rozwinięcie opisu w jednej lub więcej linii @znacznik - ewentualny znacznik lub znaczniki */ /** *Linia z ogólnym opisem klasy, metody lub pola danych. *Ewentualne rozwinięcie opisu w jednej lub więcej linii *@znacznik - ewentualny znacznik lub znaczniki */
Przykład kodu Javy z komentarzami dokumentującymi:
/** Klasa punkt reprezentuje punkt na wykresie. @author Artur Tyloch @version 1.0 z dnia 03.grudnia.1996 */ public class Point { /** Pole wsp_x określa współrzędną x punktu. Ewentualne rozwinięcie opisu w jednej lub wielu liniach. */ public int wsp_x; /** Pole wsp_y określa współrzędną y punktu */ public int wsp_y; /** *Konstruktor bezparametrowy klasy Point */ public Point(){ wsp_x=0; wsp_y=0; } /** Konstruktor klasy Point z dwoma parametrami @param x inicjalizuje pole wsp_x klasy Point @see Point @param y inicjalizuje pole wsp_y klasy Point */ public Point(int x, int y) { wsp_x=x; wsp_y=y; } }