5. óra (2017.10.09.)
Diák
Feladatok
Egészítsétek ki a matrix_orig.zip kódot, amíg az összes teszt át nem megy. Ehhez a hiányzó összeadás implementációt és az érvénytelen esetekre kivételdobást kell megvalósítanotok. (megoldás) (egy másik megoldás egy tömbbel és index függvénnyel)
Az előző példában a kivételt cseréljétek le saját kivételtípusra. (megoldás)
Az legelső példában szereplő kódot egészítsétek ki dokumentációs kommentekkel és generáljatok belőle Javadoc-ot. (megoldás)
Olvassatok be mátrixot fájlból a matrix_from_file_orig.zip kódból kiindulva. Hasznos lehet:
(megoldás BufferedReader-rel) (megoldás BufferedReader-rel és try-with-resource blokkal)
Kivételkezelés
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] [...]