Forrás dokumentáció – Javadoc / Mi is az a JAVADOC?
A kódírás fontos része a dokumentálás. Szerencsére JAVA-ban elég jól kitalálták. A nyelv a JAVADOC szerinti comment írást támogatja leginkább, amire a különböző eszközök kiváló támogatást is nyújtanak. A JAVA fordító környezet lehetőséget biztosít a forrásban elhelyezett szabványos leírókból dokumentáció készítését.
Hogy lehet a kódot dokumentálni?
A nyelv többféle lehetőséget ad komment írására:
1. dokumentálás: /**.
2. documentation */.
3. Osztály, interfész, metódus, konstruktor vagy adattag deklarációja előtt helyezhető el.
4. avadoc TAG-eket lehet használni.
5. szabványos HTML TAG-eket lehet használni a leíró részben.
A blokk címke ( block tag)
A többször is előforduló blokk címkéket egy csoportban ajánlott megadni. Az alábbi sorrendben ajánlott a megadás:
1. @author: Szerzők nevének megadására szolgáló címke.
2. @version:
3. @param: Az adott nevű paraméter leírást szolgáltatja.
4. @return: Metódus visszatérési értékét szolgáltatja.
5. @exception/@throws: Metódus vagy konstruktor által dobott kivétel dokumentálására szolgál.
6. @see: Hivatkozás elhelyezésére szolgál.
7. @serial/@serialField/@serialData:
8. @deprecated: Azt jelzi, hogy a dokumentált entitás elavult, használata kerülendő.
Szövegközi címke (inline tag)
1. {@code szöveg}: A szöveg megjelenítése fix szélességű betűtípussal (programkódként).
2. {@docRoot}: A generált állományokat tartalmazó könyvtárstruktúra gyökerének relatív elérési útvonalát szolgáltatja.
3. {@index “kifejezés” leírás}: Annak jelzésére szolgál, hogy az adott szó vagy kifejezés az adott opcionális leírással
együtt meg kell, hogy jelenjen.
4. {@inheritDoc}: Dokumentáció másolása a „legközelebbi” ősosztályból vagy implementált interfészből.
5. {@link csomag.osztály#tag címke}: Hiperhivatkozás az adott csomag, osztály, interfész, metódus, konstruktor vagy adattag
dokumentációjára.
6. {@linkplain csomag.osztály#tag címke}: Ugyanaz, mint a {@link}, csak normál betűtípussal történik a megjelenítés.
7. {@literal szöveg}: Ugyanaz, mint a {@code}, csak a szöveg megjelenítése normál betűtípussal történik.
8. {@summary szöveg}: A fő leírás első mondatát jelzi.
9. {@value csomag.osztály#adattag}: Az adott konstans adattag értékét szolgáltatja, csak final módosító esetén használható.