arckép

Neuwirth István

programtervező informatikus MSc – ELTE

Computational and Software Techniques MSc – Cranfield, UK

Elérhetőség
pitta2@gmail.com
+36 30 329 3039

Valid XHTML 1.0 Transitional

Valid CSS!

5. óra (2010.10.09.)

Javadoc

A Javadoc eszköz segítségével (a JDK tartalmazza) a forráskódba írt dokumentációs kommentek alapján HTML formátumú dokumentáció generálható. A legismertebb Javadoc dokumentáció a Java SE platform saját Javadoc oldala.

Dokumentációs kommentek

A többsoros kommentek közül azokat, amelyek /** sorozattal kezdődnek, dokumentáció kommentnek nevezzük. A Javadoc kommentek nem állhatnak kódblokkon belül, osztályt, mezőt, konstruktort vagy metódust kell megelőznie. A kommentekből HTML kód generálódik, ezért a HTML tagek használhatók a kommentekben is. Célszerű ezeket a p, br, ul/ol, table/td/tr/th, b/i tagekre korlátozni, hogy a kapott dokumentáció nem csússzon szét (például ne használjunk hx tageket, hogy ne ütközzünk ezek eredeti céljával a Javadocban).

Példa metódus dokumentációs kommentjére:

/**
 * Visszaadja a megadott oszlop- és sorindexen álló elemet a mátrixnak.
 *
 * @param row a sor indexe (1-től kezdve)
 * @param column az oszlop indexe (1-től kezdve)
 * @return a megadott helyen álló elem
 */
public int getElement(int row, int column) {
	return elements[index(row, column)];
}

A kommentek tartalmazhatnak általános leírást, illetve ezután Javadoc block tageket. A block tagek @[tag neve] ([paraméter]) [leírás] alakban állnak, belőlük a Javadocon belül a dokumentáció részletesebb részei (details részek) generálódnak ki. A kommentek általános leírásain, illetve a block tagek leírásain belül inline tageket használhatunk, amikkel például más Java osztályokra hozhatunk létre hivatkozást vagy fix széles betűtípussal szedett szöveget illeszthetünk be:

/**
 * Letrehoz egy uj matrix peldanyt megadott {@code width} szelesseggel es {@code height} magassaggal.
 *
 * @param width matrix oszlopainak szama (legalabb 1)
 * @param height matrix sorainak szama (legalabb 1)
 */
public Matrix(int width, int height) {
	...
}

Javadoc készítése

Ha a JDK bin könyvtára elérhető a PATH környezeti változón keresztül, akkor a javadoc parancs elérhető kell legyen. A parancsot magában kiadva megkapjuk a használható kapcsolókat.

Futtatás:

javadoc [csomagok nevei] [osztályok nevei]

Érdemes a rekurzív fordításnál megismert módszert alkalmazni a Javadoc készítéséhez is, az ott kigenerált forrásfájllista ugyanis itt is alkalmazható:

javadoc @sources.txt

Érdemes a Javadoc futtatásakor a forrásoktól elszeparált könyvtárba generáltatni a HTML kódokat, ehhez a -d kapcsolót használhatjuk:

javadoc -d [out könytár] [...]

Házi feladat

Az órai mátrixos példa átírása tömbök tömbjére, generált Javadockal. A binárisokat (class fájlokat) nem kell csatolni!

Feladatok

Vissza