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:

• Natychmiast przed definicją klasy;
• Natychmiast przed metodą publiczną;
• Natychmiast przed publicznym

Pierwsza linia każdego komentarza dokumentującego ma szczególne znaczenie. Jest używana jako ogólny opispatrz 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:

znaczniki definicji klasy;

@see

@see  MojaKlasa

@see

@see  MojaKlasai#mojaFunkcja

@see

@see  MojPakiet.MojaKlasa

@see

@see MojPakiet.MojaKlasa#mojaFunkcja

@version

@version 2.01 

@author

@author Artur Tyloch 

znaczniki definicji zmiennych;

@see (dowolny z powyższych znaczników)

znaczniki definicji metod;

@see (dowolny z powyższych znaczników)

@return

@return Lokalną datę 

@param

@param n Liczba szukanych  książek 

@exception

@exception MojWyjatek dzielenie liczby przez 0  

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