Dokumentowanie kodu w JAVA

 

Słowem wstępu 

W trakcie tworzenia kodu programistycznego, korzystamy z różnych klas i metod, których działania możemy nie znać. 
Z działaniem danej klasy lub metody możemy zapoznać się korzystając z dokumentacji  udostępnianej przez firmę Oracle:
https://docs.oracle.com/javase/8/docs/api/

Rys. 1. Przykładowy wygląd dokumentacji JAVA.

 

Podczas swojej przygody z programowaniem w JAVA  w laboratorium, oraz w późniejszej karierze jako developer, będziecie tworzyć własne klasy i metody.
Będą to klasy, z których zapewne będą korzystać też inni programiści i warto zadbać o to, aby mogli oni  zapoznać się ze wszystkimi funkcjonalnościami Waszego kodu.
W tym celu możecie stworzyć własną dokumentację. Nie jest to zadanie trudne, ponieważ stworzenie strony z dokumentacją (jak na Rys. 1) odbywa się w sposób automatyczny.
Jedyne o czym należy pamiętać, to umieszczanie odpowiednich komentarzy 

 

Budowa komentarzy.

Kiedy piszemy nasz kod programistyczny możemy zamieszczać w nim komentarze. Najprostszym komentarzem jest użycie dwóch ukośników (//)

Wielowierszowy komentarz możemy zrobić wpisując /* w linii poczatkowej, natomiast zakończenie komentarza będzie oznaczone przez */ . 
Poszczególne wiersze komentarza wielowierszowego beda rozpoczynać się od symbolu *.

Zerknijmy na poniższy przykład.

Comments.java

/*
*  To jest komentarz wielowierszowy, gdzie możemy umieścić sobie 
*  jakąś informację. Ta część kodu nie będzie kompilowana w Eclipse.
*  Ważne, aby wielowierszowy komentarz rozpoczynał się od /*
*  kolejne wiersze zaczynały od * , natomiast całość kończyła znakami */ 
*/

public class Comments 
{
	// To jest komentarz jednolinijkowy
	
	public Comments()	// konstruktor naszej klasy zapisany przy pomocy komentarza jednolinijkowego
	{
		x = 0;
		y = 0;
		z = 0;
	}
}

 

My jednak będziemy używać innego rodzaju komentarzy, które posłużą do wygenerowania dokumentacji JavaDoc naszej klasy, jej metod i wszystkich argumentów do nich.

 

Tworzymy komentarze projektowe

Komentarz projektowy jest podobny do komentarza wielolinijkowego z tą różnicą, że zaczynamy go od   /** (muszą być dwie gwiazdki, nie jedna)

 

Main.java

package dokumentowanie

/**
*   To jest komentarz dokumentacyjny, w ktorym mozemy scharakteryzowac nasza klase.
*   Informacje tu zawarte zostana zamieszczone w wygenerowanym pliku Javadoc naszej klasy.
*/

public class Main 
{

	public static void main(String[] args) 
	{
	     System.out.println("Hello World");	
	}
}

 

Teraz wygenerujemy nasz pierwszy plik Javadoc naszej klasy. Z menu górnego w Eclipse wybieramy Project -> Generate Javadoc

 

 

W oknie, które się pojawi zaznaczamy nasz projekt i wciskamy Finish

 

Teraz w Eclipse zobaczymy nowy folder doc. W nim wygenerowane zostały wszystkie pliki dokumentacji projektowej naszej klasy. 
Uruchomimy teraz plik index.html  W pliku widać na razie tylko nasz jeden komentarz, który zamieściliśmy w kodzie programu.

 

Stworzyliśmy nasz pierwszy plik Javadoc. Teraz dodamy szczegóły do dokumentacji.

Możemy dodać takie informacje jak autor klasy, wersja klasy, parametry wejściowe, itd... Można równiez posługiwać się znacznikami HTML aby modyfikować tekst.
Informacje o autorze, wersji ustawiamy tagami rozpoczynającymi się od @.

Main.java

package dokumentowanie

/**
*   Klasa <code>Main</code> jest klasa przykladowa.
*   Mozna tu uzywac znacznikow <b>HTML</b> i w ten sposob <i>modyfikowac</i> tekst.
*   <u>Na przyklad</u> <sub>indeks dolny</sub> oraz <sup>indeks gorny</sup>
*   @author Daniel Budaszewski
*   @version 1.0.0   21/02/2023
*/

public class Main 
{

	public static void main(String[] args) 
	{
	     System.out.println("Hello World");	
	}
}

 

Teraz nasz plik Javadoc będzie wygladał następująco:

 

 Dokumentowania ciąg dalszy

Teraz pora utworzyć dokumentacje do konstruktorów i  metod.

Stwórzmy sobie nową klasę Student, na której prześledzimy inne rodzaje tagów.

Student.java

package dokumentowanie;

/**
 * 
 * @author Daniel
 * @version 1.0.0 
 */

public class Student 
{
    /**
     * Imie studenta.
     */
    private String imie;
    /**
     * Nazwisko studenta.
     */
    private String nazwisko;
    /**
     * Numer indeksu studenta.
     */
    private int index;
    
    
    /**
     * Konstruktor domyslny.
     * Tutaj mozemy go opisac.
     */
    public Student()
    {
        
    }
    
    /**
     * Konstruktor pobierajacy dwa parametry: imie i nazwisko.
     * @param Imie  opisuje imie studenta.
     * @param Nazwisko  opisuje nazwisko studenta.
     */
    public Student(String imie, String nazwisko)
    {
        this.imie = imie;
        this.nazwisko = nazwisko;
    }
    
    /**
     * Konstruktor pobierajacy parametry: imie, nazwisko, numer indeksu.
     * @param imie opisuje imie studenta.
     * @param nazwisko opisuje nazwisko studenta.
     * @param index  To jest numer indeksu.
     * @since 1.0.1
     * @see dokumentowanie.Student#setIndex(int)
     */
    public Student (String imie, String nazwisko, int index)
    {
        this(imie, nazwisko);
        this.index = index;
    }
    
    /**
     * 
     * @param numer  ustawia nowy numer indeksu studenta.
     */
    public void setIndex(int numer)
    {
        this.index = numer;
    }
    
    /**
     * 
     * @return zwraca numer indeksu studenta.
     */
    public int getIndex()
    {
        return index;
    }
}

 

Zwróćmy teraz uwagę na nastepujące tagi wystepujące w komentarzach dokumentujacych:

• @author   - definiuje kto jest autorem klasy.
• @version  - określa wersję klasy.
• @param   - opisuje parametr wejściowy klasy lub metody.
• @since   - określa od której wersji klasy istnieje dana funkcjonalność.
• @see   - ustawia referencję do danego punktu w klasie.
• @return   - definiuje co jest zwracane w opisywanej metodzie.

 

Dokumentacja klasy Student będzie teraz wyglądać następująco: