Komentarze

Komentarze "standardowe"

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
*/

Komentarze dokumentujące

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:

  1. Nagłówek.
  2. Diagram hierarchii klas.
  3. Opis klasy.
  4. Posortowany indeks publicznych pól danych.
  5. Indeks konstruktorów.
  6. Posortowany indeks metod publicznych.
  7. Opis zmiennych publicznych w kolejności, w której pojawiają się w pliku źródłowym.
  8. Opis konstruktorów publicznych w kolejności w której pojawiają się w pliku źródłowym.
  9. Opis metod publicznych w kolejności w której pojawiają się w pliku źródłowym.

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;
}
}