Dokumentálja automatikusan Java kódját a Javadoc segítségével

Ha bármilyen programozást végez, tisztában lesz vele, hogy az egyik legunalmasabb feladat a kód dokumentálása. Függetlenül attól, hogy enyhén bosszantónak találja, vagy olyan vállalkozásról van szó, amelytől teljes rettegésben néz szembe, a kóddokumentáció elengedhetetlen. Másoknak meg kell érteniük a kódod működését, és akár te is közéjük tartozhatsz, ha később elolvasod!

A Java kényelmesen beépített megoldást kínál a problémára: Javadoc.

A Javadoc segítségével automatikusan dokumentálhatja kódját

Remélhetőleg már követed jó kódolási gyakorlat és tartalmazzon magyarázó megjegyzéseket a kódjában. Noha az ilyen típusú kódon belüli megjegyzések minden bizonnyal hasznosak, valójában nem nyújtanak semmi hasonlót egy kézikönyvhöz.

Természetesen egy másik programozó átnézheti a kódot, és elolvashatja az előtte álló osztályokat, metódusokat és függvényeket. Rendkívül nehéz azonban jó áttekintést kapni az összes kódról, vagy olyan funkciókat találni, amelyek hasznosak lehetnek, ha nem tudja, hogy léteznek. A Javadoc célja a probléma megoldása.

A Javadoc automatikusan generál egy részletes és olvasóbarát HTML kézikönyvet az összes kódhoz. A legjobb az egészben, hogy ezt olyan kódmegjegyzések használatával teszi, amelyeket valószínűleg már ír.

Mi is pontosan az a Javadoc, és hogyan működik?

A Javadoc egy önálló program, amely az Oracle Java fejlesztőkészletének (JDK) kiadásaival együtt érkezik. Valójában nem töltheti le külön. Amikor letölti és telepítse az Oracle JDK egyik verzióját, telepíti a Javadoc-ot is.

Amikor futtatja, a Javadoc HTML-dokumentációt állít elő a Java-forráskódban található speciálisan formázott megjegyzésekből. Ez a folyamat hasznosabb, olvashatóbb dokumentációt hoz létre, miközben ösztönzi a legjobb gyakorlatokat.

Dióhéjban a Javadoc lehetővé teszi a kód és a dokumentáció egyidejű megírását. Leegyszerűsíti a munkafolyamatot, és lehetővé teszi az idő hatékonyabb felhasználását.

A Javadoc úgy működik, hogy elemzi a speciálisan formázott megjegyzéseket a kódban, és konvertálja azokat HTML-kimenetté. Az egyetlen változtatás, amit valóban meg kell tennie, az az, hogy bizonyos karakterláncokat belefoglal a megjegyzéseibe. Ezek segítségével a Javadoc tudja, mit szeretne belefoglalni a végső dokumentációba.

A Javadoc megjegyzéseknek közvetlenül az osztály-, mező-, konstruktor- vagy metódusdeklaráció előtt kell lenniük. Magának a megjegyzésnek:

• Kezdje a három karakterrel /**.
• Minden új sor elejére tegyen egy csillagot.
• Zárja be a két karakterrel */.

A megjegyzésekben HTML-kódot is beilleszthet a végső kimenetbe, és olyan címkéket is beilleszthet, amelyek hivatkozásokat generálnak a kódbázis releváns részeire. Használhat olyan dolgokat is, mint például a HTML képcímkék, hogy képeket adjon a végső dokumentációhoz. Miután megszokta a formátumot és a rendelkezésre álló címkéket, az ilyen megjegyzések írása gyerekjáték.

Íme egy példa az egyszerű Javadoc megjegyzések illusztrálására, amelyek olyan függvényt írnak le, amely képet kap egy URL-ből, és kinyomtatja a képernyőre. A megjegyzés közvetlenül a függvény előtt áll, és leírja, hogy mit csinál. Ez a megjegyzésblokk három szakaszspecifikus címkét is használ: @param, @Visszatérés, és @lát.

/**
* Egy kép objektumot ad vissza, amelyet azután a képernyőre lehet festeni.
* Az url argumentumnak abszolút értéket kell megadnia {@link URL}. A név
* Az argumentum az url argumentumhoz viszonyított specifikáció.
* 

* Ez a metódus mindig azonnal visszatér, függetlenül attól, hogy a
* kép létezik. Mikor ez Az applet megpróbálja rárajzolni a képet
* a képernyő, az adatok betöltődnek. A grafikai primitívek
* amelyek rajzolják a képet, fokozatosan festik a képernyőt.
*
* @param url egy abszolút URL, amely a kép alap helyét adja meg
* @param nevezze meg a kép helyét az url argumentumhoz viszonyítva
* @Visszatérés a kép a megadott URL-en
* @lát Kép
*/
nyilvános Kép getImage(URL url, karakterlánc neve){
próbálja meg {
Visszatérés getImage(új URL(url, név));
 } fogás (Rosszul formált URL kivétel e) {
Visszatérésnulla;
 }
}

Amikor a Javadoc feldolgozza a fenti kódot, a következőhöz hasonló weboldalt hoz létre:

A böngésző nagyjából ugyanúgy jeleníti meg a Javadoc kimenetet, mint bármely HTML dokumentumot. A Javadoc figyelmen kívül hagyja a szóközöket és a sortöréseket, hacsak nem használ HTML-címkéket a szóköz létrehozásához.

A megjegyzés végén használt @tagok generálják a Paraméterek, Visszatér, és Lásd még szakaszok, amelyeket lát.

Követned kell a @param tag a paraméter nevével, szóközzel és leírásával. A fenti esetben két paraméter van: url és név. Figyelje meg, hogy mindkettő ugyanazon Paraméterek címsor alatt jelenik meg a dokumentáció kimenetében. Felsorolhat annyi paramétert, amennyi a leírt függvényhez vagy módszerhez szükséges.

Az @Visszatérés tag dokumentálja a függvény által visszaadott értéket, ha egyáltalán visszaadja. Ez lehet egy egyszerű egyszavas leírás vagy több mondat is, a körülményektől függően.

Az @lát címke lehetővé teszi más kapcsolódó vagy releváns funkciók címkézését. Ebben az esetben a @see címke egy másik, egyszerűen képnek nevezett függvényre utal. Vegye figyelembe, hogy az ezzel a címkével készített hivatkozások kattintható hivatkozások, amelyek lehetővé teszik az olvasó számára, hogy a hivatkozott elemre ugorjon a végső HTML-ben.

Több címke is elérhető, például @version, @author, @exception és mások. Megfelelő használat esetén a címkék segítenek az elemek egymáshoz való viszonyításában, és megkönnyítik a dokumentációban való navigálást.

Javadoc futtatása a forráskódon

A Javadoc-ot a parancssorban hívja meg. Futtathatja egyes fájlokon, teljes könyvtárakon, Java-csomagokon vagy egyedi fájlok listáján. Alapértelmezés szerint a Javadoc abban a könyvtárban hozza létre a HTML dokumentációs fájlokat, ahová a parancsot beírja. Ha segítséget szeretne kapni az elérhető parancsokkal kapcsolatban, egyszerűen írja be:

javadoc --Segítség

Ha szeretné részletesebben látni, hogy pontosan mire képes a Javadoc, tekintse meg a hivatalos dokumentációt Jóslat. Ha egyetlen fájlban vagy könyvtárban szeretne gyors dokumentációt létrehozni, akkor beléphet javadoc a parancssorban egy fájlnév vagy helyettesítő karakter után.

javadoc ~/code/fájlnév.java
javadoc ~/code/*.Jáva

Fent található a Javadoc által létrehozott fájlok és könyvtárak listája. Amint látja, elég sok van belőlük. Emiatt ügyeljen arra, hogy a program futtatásakor ne legyen ugyanabban a könyvtárban, mint a forráskód. Ha így tesz, akkora zűrzavar keletkezhet.

Az újonnan létrehozott dokumentumok megtekintéséhez egyszerűen nyissa meg a index.html fájlt a kívánt böngészőben. A következőhöz hasonló oldalt fogsz kapni:

Ez egy egyetlen, rövid Java osztály dokumentációja a kimenet bemutatására. A fejléc az osztály nevét, valamint a benne szereplő metódusokat mutatja. Ha lefelé görget, az egyes osztálymetódusok részletesebb meghatározásai láthatók.

Mint látható, bármilyen típusú Java projektnél, különösen a nagyoknál, sok ezer sornyi kóddal, az ilyen típusú dokumentáció felbecsülhetetlen értékű. Nagy kihívás lenne megismerni egy nagy kódbázist a forráskódjuk átolvasásával. A Javadoc oldalak ezt a folyamatot sokkal gyorsabbá és könnyebben követhetővé teszik.

A Javadoc segíthet abban, hogy a Java-kódot és az összes vonatkozó dokumentációt rendszerezetten és könnyen használhatóan tartsa. Akár a feledékeny jövőbeli énedért teszed, akár azért, hogy megkönnyítsd egy nagy csapat dolgát, A Javadoc egy hatékony eszköz, amely megváltoztathatja az írási és a Java kódolási műveletek módját projektek.

A 8 legjobb Java-blog programozóknak

Olvassa el a következőt