Dokumentujte svoj kód Java automaticky pomocou Javadoc

Ak robíte akýkoľvek druh programovania, budete si dobre vedomí toho, že jednou z najúnavnejších úloh je dokumentovanie vášho kódu. Či už to považujete za mierne otravné alebo za podnik, ktorému čelíte absolútneho strachu, dokumentácia kódu je nevyhnutná. Ostatní musia pochopiť, ako váš kód funguje, a vy môžete byť jedným z nich, ak ho budete čítať neskôr!

Java pohodlne poskytuje vstavané riešenie problému: Javadoc.

Javadoc vám môže pomôcť zdokumentovať váš kód automaticky

Dúfam, že už sledujete osvedčené postupy kódovania a zahrňte do svojho kódu vysvetľujúce komentáre. Aj keď je tento typ komentárov v kóde určite užitočný, v skutočnosti neposkytuje nič porovnateľné s manuálom.

Iste, iný programátor si môže prezrieť váš kód a prečítať si o konkrétnych triedach, metódach a funkciách, ktoré má pred sebou. Je však mimoriadne ťažké získať dobrý prehľad o celom kóde alebo nájsť funkcie, ktoré by mohli byť užitočné, keď neviete, že existujú. Javadoc sa snaží tento problém vyriešiť.

Javadoc automaticky vygeneruje podrobný a čitateľný HTML manuál pre celý váš kód. Najlepšie zo všetkého je, že to robí pomocou komentárov ku kódu, ktoré už pravdepodobne píšete.

Čo presne je Javadoc a ako to funguje?

Javadoc je samostatný program, ktorý sa dodáva spolu s vydaniami Oracle Java Development Kit (JDK). V skutočnosti si ho nemôžete stiahnuť samostatne. Keď si stiahnete a nainštalovať jednu z verzií Oracle JDK, nainštaluje aj Javadoc.

Keď ho spustíte, Javadoc vygeneruje HTML dokumentáciu zo špeciálne naformátovaných komentárov vo vašom zdrojovom kóde Java. Tento proces vytvára užitočnejšiu a čitateľnejšiu dokumentáciu a zároveň podporuje osvedčené postupy.

Stručne povedané, Javadoc vám umožňuje písať váš kód a jeho dokumentáciu súčasne. Zjednodušuje váš pracovný postup a umožňuje efektívnejšie využívať váš čas.

Javadoc funguje tak, že analyzuje špeciálne naformátované komentáre vo vašom kóde a konvertuje ich na výstup HTML. Jedinou zmenou, ktorú skutočne musíte urobiť, je zahrnúť do komentárov určité reťazce. Vďaka nim bude Javadoc vedieť, čo chcete zahrnúť do konečnej dokumentácie.

Komentáre Javadoc by mali bezprostredne predchádzať deklarácii triedy, poľa, konštruktora alebo metódy. Samotný komentár by mal:

• Začnite s tromi postavami /**.
• Na začiatok každého nového riadku vložte hviezdičku.
• Zatvorte pomocou dvoch znakov */.

V rámci komentárov môžete do konečného výstupu zahrnúť HTML a zahrnúť značky, ktoré vygenerujú odkazy na relevantné časti vašej kódovej základne. Na zahrnutie obrázkov do konečnej dokumentácie môžete dokonca použiť veci, ako sú značky obrázkov HTML. Keď si zvyknete na formát a dostupné značky, písanie takýchto komentárov je hračka.

Tu je príklad na ilustráciu jednoduchých komentárov Javadoc popisujúcich funkciu, ktorá získa obrázok z adresy URL a vytlačí ho na obrazovku. Komentár bezprostredne predchádza funkciu a popisuje, čo robí. Tento blok komentárov tiež využíva tri značky špecifické pre sekciu: @param, @návrata @pozri.

/**
* Vracia obrazový objekt, ktorý možno potom namaľovať na obrazovku.
* Argument adresy URL musí špecifikovať absolútnu hodnotu {@odkaz URL}. Názov
* argument je špecifikátor, ktorý je relatívny k argumentu url.
* 

* Táto metóda sa vždy vráti okamžite, či už je alebo nie
*obrázok existuje. Kedy toto applet sa pokúša nakresliť obrázok
* na obrazovke sa načítajú údaje. Grafické primitívy
* ktoré vykreslia obrázok sa postupne vyfarbia na obrazovku.
*
* @param url absolútnu webovú adresu s uvedením základnej polohy obrázka
* @param pomenujte umiestnenie obrázka vzhľadom na argument url
* @návrat obrázok na zadanej adrese URL
* @pozri Obrázok
*/
verejnosti Obrázok getImage(URL URL, názov reťazca){
skúste {
vrátiť getImage(Nový URL(url, meno));
 } chytiť (MalformedURLException e) {
vrátiťnulový;
 }
}

Keď Javadoc spracuje vyššie uvedený kód, vygeneruje webovú stránku podobnú nasledujúcej:

Prehliadač vykresľuje výstup Javadoc takmer rovnakým spôsobom, ako zobrazuje akýkoľvek dokument HTML. Javadoc ignoruje nadbytočné medzery a zalomenia riadkov, pokiaľ na vytvorenie tohto priestoru nepoužívate značky HTML.

@tagy použité na konci komentára generujú Parametre, Návratya Pozri tiež sekcie, ktoré vidíte.

Mali by ste postupovať podľa @param tag s názvom parametra, medzerou a jeho popisom. Vo vyššie uvedenom prípade existujú dva parametre: url a názov. Všimnite si, že obe sa vo výstupe dokumentácie zobrazujú pod rovnakým nadpisom Parametre. Môžete uviesť toľko parametrov, koľko je potrebných pre funkciu alebo metódu, ktorú popisujete.

The @návrat tag dokumentuje hodnotu, ktorú funkcia vracia, ak vôbec. Môže to byť jednoduchý jednoslovný opis alebo veľa viet, v závislosti od okolností.

The @pozri tag vám umožňuje označiť ďalšie funkcie, ktoré súvisia alebo sú relevantné. V tomto prípade značka @see odkazuje na inú funkciu nazývanú jednoducho Obrázok. Upozorňujeme, že odkazy vytvorené pomocou tejto značky sú klikateľné odkazy, ktoré umožňujú čitateľovi prejsť na odkazovanú položku v konečnom HTML.

K dispozícii je viac značiek, ako napríklad @version, @author, @exception a iné. Pri správnom používaní pomáhajú štítky navzájom spájať položky a umožňujú jednoduchú navigáciu v dokumentácii.

Spustenie Javadoc na vašom zdrojovom kóde

Javadoc vyvoláte na príkazovom riadku. Môžete ho spustiť na jednotlivých súboroch, celých adresároch, balíkoch java alebo cez zoznam jednotlivých súborov. V predvolenom nastavení Javadoc vygeneruje súbory HTML dokumentácie v adresári, do ktorého zadáte príkaz. Ak chcete získať pomoc ku konkrétnym dostupným príkazom, jednoducho zadajte:

javadoc --Pomoc

Ak chcete presne vidieť, čo Javadoc dokáže podrobnejšie, pozrite si oficiálnu dokumentáciu Oracle. Ak chcete vytvoriť rýchly súbor dokumentácie o jednom súbore alebo adresári, môžete zadať javadoc na príkazovom riadku, za ktorým nasleduje názov súboru alebo zástupný znak.

javadoc ~/code/názov súboru.java
javadoc ~/code/*.java

Vyššie je zoznam súborov a adresárov, ktoré Javadoc vytvoril. Ako vidíte, je ich pomerne veľa. Z tohto dôvodu by ste si mali byť istí, že sa pri spustení programu nenachádzate v rovnakom adresári ako váš zdrojový kód. Mohlo by to spôsobiť poriadny neporiadok.

Ak chcete zobraziť svoje novovytvorené dokumenty, jednoducho otvorte súbor index.html súbor vo vašom preferovanom prehliadači. Dostanete stránku, ako je táto:

Toto je dokumentácia pre jednu krátku triedu Java na demonštráciu výstupu. Hlavička zobrazuje názov triedy, ako aj metódy, ktoré sú v nej zahrnuté. Rolovanie nadol odhaľuje podrobnejšie definície každej z metód triedy.

Ako vidíte, tento typ dokumentácie je neoceniteľný pre akýkoľvek typ projektu Java, najmä pre veľké projekty s tisíckami riadkov kódu. Bolo by náročné dozvedieť sa o veľkej kódovej základni čítaním jej zdrojového kódu. Stránky Javadoc tento proces oveľa rýchlejšie a jednoduchšie sledujú.

Javadoc vám pomôže udržať váš kód Java a všetku relevantnú dokumentáciu usporiadanú a jednoducho použiteľnú. Či už to robíte pre svoje zábudlivé budúce ja, alebo aby ste veci uľahčili veľkému tímu, Javadoc je výkonný nástroj, ktorý môže zmeniť spôsob, akým píšete, a interakciu s vaším kódovaním Java projektov.

8 najlepších Java blogov pre programátorov

Prečítajte si ďalej