A Javadoc

Alapvetően jó ötlet, ha saját magunk (vagy más programozók akik a kódunkat használják) kedvéért apró megjegyzéseket teszünk a programba. Remélhetőleg nem gonoszkodó megjegyzéseket, hogy "dik má, gergya ez a for ciklus", hanem olyan megjegyzéseket, amik segítenek és egyértelművé teszik a program használatát.

Például, tegyük fel, hogy létre akarunk hozni egy kólát:

Innivalo kola=new Innivalo("Coca Cola",5,0);

No most, honnan fogjuk tudni, hogy:

• miért pont két számot kell megadni
• egyáltalán, egész vagy tört számokat lehet használni?
• okés, név, méret, alkohol, de a méret az most literben, deciben, vagy miben van?

Fogalmunk sincs róla (főleg, ha már két hete csináltuk az Innivalot), ezért belenézünk az Innivalo osztályba, hátha találunk valami segítséget:

public class Innivalo {
    private double felszolgaltMeret=5; // dl
    private double alkoholTartalomSzazalek=4; // %
    private String nev;

    protected Innivalo(String nev,double felszolgaltMeret,double alkoholTartalomSzazalek) {
        this.nev=nev;
        this.felszolgaltMeret=felszolgaltMeret;
        this.alkoholTartalomSzazalek=alkoholTartalomSzazalek;
    }

    ...stb...

Nos, segítségből nem sok van, de ott van valami kis megjegyzés, hogy a felszolgált méret dl-ben van.

Hát izé... a dolog megvan, de azért nem mondhatni, hogy kifejezetten kényelmes volt, nem?

Javadoc kommentek

A Javadoc view-ről már volt szó, ez úgy tűnik, hogy segít nekünk megmutatni, hogy hova mit lehet írni. Hogyan tudjuk a saját osztályainkat is felokosítani?

Amennyiben a megjegyzéseket úgy rakjuk a programba, hogy /** -vel kezdődnek, és néhány mágikus formai követelménynek megfelelnek, akkor lett egy Javadoc kommentünk (azaz Javadoc-os megjegyzésünk). A konstruktor kommentezve így néz ki:

public class Innivalo {
    private double felszolgaltMeret=5; // dl
    private double alkoholTartalomSzazalek=4; // %
    private String nev;

    /**
     * Új innivaló létrehozása.
     * 
     * @param nev az innivaló neve
     * @param felszolgaltMeret a felszolgálási méret deciliterben
     * @param alkoholTartalomSzazalek az alkoholtartalom százalékban
     */
    protected Innivalo(String nev,double felszolgaltMeret,double alkoholTartalomSzazalek) {
        this.nev=nev;
        this.felszolgaltMeret=felszolgaltMeret;
        this.alkoholTartalomSzazalek=alkoholTartalomSzazalek;
    }

Ezután rögtön tudja a dolgát! A Ctrl+SPACE megnyomásával nem csak a lehetséges metódusokat kapjuk meg, hanem a kiválaszott metódus Javadoc-át is, ha a konstruktort meg akarjuk hívni:

Természetesen ha akarod, a Javadoc view-t bekapcsolhatod az alsó panelen, így mindennek látszik a Javadoc-a:

Az Eclipse annyira okos, hogy azt is tudja, ha valami nem szó szerint az Innivalo konstruktorának hívása, de mégiscsak az. Például, amikor az ős-osztály konstruktorát hívjuk, tudja, hogy az egy Innivalo konstruktor:

Azt még el sem merem árulni, hogy a Javadoc kommentekből a javadoc programmal egy teljes weboldalnyi dokumentációt lehet elkészíteni a teljes programodról, teljesen automatikusan.

Katt a String osztály doksijára!

Javadoc erőfeszítés nélkül

Javadoc kommentet kell tenni:

• az osztályra
• az összes public metódusra
• az összes public attribútumra

Illik tenni a protected dolgokra is, viszont a private dolgokra egyáltalán nem muszáj. Vajon miért van így? Hmm hmm, gondolkozz!

Most már eleget gondolkoztál, igen, pont azért! A private dolgok nem látszódnak kívülről, így senkinek semmi köze hozzá, így nem is használhatja, így nem is láthatja, így felesleges kommentezni is. Loggggikus, ugye? :)

Osztály kommenteléséhez

Menj az osztály nevére a kurzorral, majd nyomd meg a Alt+Shift+J -t!

Megjelenik egy ilyen komment blokk:

/**
 * @author Gabor
 *
 */

Ebbe írd bele azt, hogy az osztály mire való, egy mondatban.

/**
 * Az Innivaló osztály minden megiható ital ősosztálya.
 *
 * @author Gabor
 *
 */

Az author jelzés azt mondja meg, hogy ki csinálta ezt az osztályt. Ezt magától kitölti a gépre bejelentkezett felhasználó neve alapján.

Metódus kommenteléséhez

Menj a metódus nevére a kurzorral, majd nyomd meg a Alt+Shift+J -t!

Ez készít egy ilyen komment blokkot:

/**
 * @return
 */

Ebbe írd bele egy mondatban, hogy mit csinál a metódus. Amennyiben van visszatérési érték, arra egy @return rész készül, ehhez írd be, hogy mit jelent a visszaadott érték.

/**
 * Visszaadja, hogy hány deci egy pohár ilyen ital.
 *
 * @return az ital felszolgálási mérete
 */
public double getFelszolgaltMeret() {
    return felszolgaltMeret;
}

Ha egy metódusnak vannak paraméterei, akkor oda is írd be a paraméter jelentését. A paraméterek nevét automatikusan kitölti.

/**
 * Új innivaló létrehozása.
 * 
 * @param nev az innivaló neve
 * @param felszolgaltMeret a felszolgálási méret deciliterben
 * @param alkoholTartalomSzazalek az alkoholtartalom százalékban
 */
protected Innivalo(String nev,double felszolgaltMeret,double alkoholTartalomSzazalek) {

Igazán egyszerű, és így magunknak és másoknak is könnyebbé tesszük a munkát!

Feladat: Javadoc-old meg a Kocsma példa összes osztályát!