Java megjegyzések
A dokumentáció kódjának legnagyobb problémája a dokumentáció támogatása. Ha a dokumentáció és a kód el van választva, akkor nehézségek merülnek fel azzal kapcsolatban, hogy módosítani kell a kísérő dokumentáció vonatkozó részeit, amikor a kód megváltozik. A fejlesztői környezet megoldást kínál - a kód és a dokumentáció összekapcsolása, mindent egy fájlba helyezve.
A javadoc segédprogram lehetővé teszi a HTML címkék beillesztését, és speciális hivatkozásokat (leírásokat) használhat a dokumentáláshoz. Az NTML fejléc-címkéket nem használják arra, hogy ne sérüljenek a segédprogram által létrehozott fájl stílusa.
Egy változó dokumentálásához a következő leírásokat használhatja:
Az osztályok és interfészek esetében használhatsz leíróakat:
A módszereket leírók segítségével lehet dokumentálni:
A karakterek / ** kezdeti kombinációja után az osztály, a változó vagy a módszer fő leírása található. Ezután beillesztheti a különböző leírókat. Minden egyes @ leírónak az elsőnek kell lennie a karakterláncban. Több azonos típusú leírót kell csoportosítani. Beágyazott leírók (kezdőbakkokkal kezdődően) elhelyezhetők bármely leírásban.
A javadoc segédprogram a program forrásfájlját bemenetként fogadja el. Több HTML fájlt hoz létre, amely tartalmazza a program dokumentációját. Az egyes osztályokra vonatkozó információk egy különálló HTML-fájlban fognak szerepelni. Ezenkívül egy indexfa és egy hierarchia is létrejön. Más HTML fájlokat is létrehozhat.
Az Eclipse környezetben dokumentációt hozhat létre a Project / Generate Javadoc menü parancs segítségével.
A javadoc leírásai
@author leírás
-author lehetőség a mezõbe a HTML dokumentációba.
@ elavult leírás
Megadja, hogy az osztály, az interfész vagy az osztály tagja elavult. Ajánlott a @see leírók beillesztése vagy a programozó számára a rendelkezésre álló alternatívák tájékoztatása. A változók, módszerek és osztályok dokumentálására használható.
Megadja az aktuális dokumentáció gyökérkönyvtárának elérési útját.
@exception exclude_name magyarázat
Leírja a módszer kivételét. Itt a exclude_name megadja a kivétel teljes nevét, és a magyarázat olyan karakterláncot jelent, amely leírja, hogy mely esetekben lehet ez a kivétel. Csak a módszerek dokumentálására használható.
Hozzáad egy linket további információkhoz. Ha megjelenik, akkor a hivatkozásként használt szöveg (ha van).
@param paraméter_neve
Dokumentáljon paramétert az eljárás vagy paramétertípus számára az osztály vagy az interfész számára. Csak egy módszer, egy konstruktor, egy generikus osztály vagy egy interfész dokumentálására használható.
@ visszafoglalni a magyarázatot
Leírja a módszer visszatérési értékét.
@ nézze meg a package.class # tétel szövegét
Hozzáad egy linket a további információkhoz.
@serial description
@ serialData leírás
Írja be a writeObject és writeExternal módszerekkel írt adatokat.
@ serialField név típus leírása
@since kiadás
Azt jelzi, hogy az osztály vagy osztály elem először egy adott kibocsátásban került bevezetésre. Itt a kiadás jelenti azt a sort, amelyben a kiadás vagy verzió van megadva, amelyből ez a funkció elérhetővé válik.
@throws mentes név
Ugyanaz a cél, mint a @exception-leíró.
Megjeleníti a következő állandó értékét, amely a statikus mező.
Megjeleníti egy adott statikus mező értékét.
@version információk
A verzióinformációk (általában egy szám). A javadoc segédprogram futtatásakor meg kell adnia a -version opciót, amely lehetővé teszi, hogy az ismertető az NTML-ben dokumentációt tartalmazzon.