Automatski dokumentirajte svoj Java kod pomoću Javadoc-a

Ako radite bilo kakvu vrstu programiranja, bit ćete svjesni da je jedan od najdosadnijih zadataka dokumentiranje vašeg koda. Bez obzira smatrate li to malo neugodnim ili pothvatom s kojim se potpuno užasavate, dokumentacija koda je neophodna. Drugi moraju razumjeti kako vaš kod funkcionira, a možda ćete čak i biti jedan od njih ako ga kasnije budete čitali!

Java zgodno nudi ugrađeno rješenje problema: Javadoc.

Javadoc vam može pomoći da automatski dokumentirate svoj kod

Nadamo se da već pratite dobre prakse kodiranja i uključite komentare s objašnjenjima u svoj kod. Iako je ova vrsta komentiranja u kodu zasigurno korisna, zapravo ne pruža ništa usporedivo s priručnikom.

Naravno, drugi programer može pregledavati vaš kod i čitati o specifičnim klasama, metodama i funkcijama koje su pred njim. Međutim, iznimno je teško dobiti dobar pregled cijelog koda ili pronaći funkcije koje bi mogle biti korisne kada ne znate da postoje. Javadoc ima za cilj riješiti taj problem.

Javadoc će automatski generirati detaljan i razumljiv HTML priručnik za sav vaš kod. Najbolje od svega, to čini korištenjem komentara koda koje vjerojatno već pišete.

Što je zapravo Javadoc i kako radi?

Javadoc je samostalni program koji dolazi u paketu s Oracleovim izdanjima Java development kita (JDK). Zapravo, ne možete ga preuzeti zasebno. Kada preuzmete i instalirati jednu od Oracleovih JDK verzija, također će instalirati Javadoc.

Kada ga pokrenete, Javadoc generira HTML dokumentaciju iz posebno oblikovanih komentara u vašem izvornom kodu Java. Ovaj proces stvara korisniju i čitljiviju dokumentaciju, a istovremeno potiče najbolje prakse.

Ukratko, Javadoc vam omogućuje da u isto vrijeme napišete svoj kod i njegovu dokumentaciju. Pojednostavljuje vaš tijek rada i omogućuje vam učinkovitije korištenje vremena.

Javadoc radi tako što analizira posebno oblikovane komentare u vašem kodu i pretvara ih u HTML izlaz. Jedina promjena koju stvarno trebate napraviti je uključiti određene nizove u svoje komentare. To Javadoc-u daje do znanja što želite uključiti u konačnu dokumentaciju.

Javadoc komentari trebaju neposredno prethoditi deklaraciji klase, polja, konstruktora ili metode. Sam komentar bi trebao:

• Počnite s tri lika /**.
• Uključite zvjezdicu na početak svakog novog retka.
• Zatvorite s dva lika */.

Unutar komentara možete uključiti HTML u konačni rezultat i uključiti oznake koje će generirati veze na relevantne dijelove vaše baze koda. Možete čak koristiti stvari kao što su HTML oznake slika za uključivanje slika u konačnu dokumentaciju. Nakon što se naviknete na format i dostupne oznake, pisanje takvih komentara je jednostavno.

Evo primjera za ilustraciju jednostavnih Javadoc komentara koji opisuju funkciju koja dobiva sliku iz URL-a i ispisuje je na zaslon. Komentar neposredno prethodi funkciji i opisuje što ona radi. Ovaj blok komentara također koristi tri oznake specifične za odjeljke: @param, @povratak, i @vidjeti.

/**
* Vraća objekt slike koji se zatim može oslikati na zaslonu.
* Argument url mora specificirati apsolutnu vrijednost {@veza URL}. Ime
* argument je specificator koji je relativan u odnosu na argument url.
* 

* Ova metoda se uvijek vraća odmah, bez obzira na to je li ili ne
* slika postoji. Kada ovaj aplet pokušava nacrtati sliku
* na zaslonu, podaci će se učitati. Grafički primitivi
* koji crtaju sliku postepeno će slikati na zaslonu.
*
* @param url apsolutni URL koji daje osnovnu lokaciju slike
* @param imenuje mjesto slike, u odnosu na argument url
* @povratak sliku na navedenom URL-u
* @vidjeti Slika
*/
javnost Slika getImage(URL url, naziv niza){
probati {
povratak getImage(novi URL (url, naziv));
 } ulov (MalformedURLEException e) {
povrataknull;
 }
}

Kada Javadoc obradi gornji kod, generira web stranicu sličnu sljedećoj:

Preglednik prikazuje Javadoc izlaz na isti način na koji prikazuje bilo koji HTML dokument. Javadoc zanemaruje dodatni razmak i prijelome redaka osim ako ne koristite HTML oznake za stvaranje tog prostora.

@oznake korištene na kraju komentara generiraju Parametri, Vraća, i Vidi također odjeljke koje vidite.

Trebali biste slijediti @param oznaku s nazivom parametra, razmakom i njegovim opisom. U gornjem slučaju postoje dva parametra: url i Ime. Primijetite da se oba pojavljuju pod istim naslovom Parametri u izlazu dokumentacije. Možete navesti onoliko parametara koliko je potrebno za funkciju ili metodu koju opisujete.

The @povratak tag dokumentira vrijednost koju funkcija vraća, ako uopće. To može biti jednostavan opis od jedne riječi ili više rečenica, ovisno o okolnostima.

The @vidjeti tag vam omogućuje označavanje drugih funkcija koje su povezane ili relevantne. U ovom slučaju, oznaka @see odnosi se na drugu funkciju koja se zove jednostavno Slika. Imajte na umu da su reference napravljene s ovom oznakom veze na koje se može kliknuti, omogućujući čitatelju da skoči na referenciranu stavku u konačnom HTML-u.

Dostupno je više oznaka kao što su @version, @author, @exception i druge. Kada se pravilno koriste, oznake pomažu u međusobnom povezivanju stavki i omogućuju jednostavno kretanje kroz dokumentaciju.

Pokretanje Javadoc-a na vašem izvornom kodu

Pozivate Javadoc u naredbenom retku. Možete ga pokrenuti na pojedinačnim datotekama, cijelim direktorijima, java paketima ili na popisu pojedinačnih datoteka. Javadoc će prema zadanim postavkama generirati datoteke HTML dokumentacije u direktoriju u koji unesete naredbu. Da biste dobili pomoć o određenim dostupnim naredbama, jednostavno unesite:

javadoc --Pomozite

Da biste vidjeli što točno Javadoc može učiniti detaljnije, pogledajte službenu dokumentaciju iz Oracle. Da biste stvorili brzi skup dokumentacije za jednu datoteku ili direktorij, možete unijeti javadoc u naredbenom retku nakon čega slijedi naziv datoteke ili zamjenski znak.

javadoc ~/code/naziv datoteke.java
javadoc ~/code/*.Java

Iznad je popis datoteka i direktorija koje je Javadoc stvorio. Kao što vidite, ima ih poprilično. Iz tog razloga, trebali biste biti sigurni da se ne nalazite u istom direktoriju kao i vaš izvorni kod kada pokrenete program. To bi moglo stvoriti popriličan nered.

Da biste vidjeli svoje novostvorene dokumente, jednostavno otvorite index.html datoteku u željenom pregledniku. Dobit ćete stranicu poput ove:

Ovo je dokumentacija za jednu, kratku Java klasu za demonstriranje rezultata. Zaglavlje prikazuje naziv klase kao i metode uključene u nju. Pomicanje prema dolje otkriva detaljnije definicije svake metode klase.

Kao što možete vidjeti, za bilo koju vrstu Java projekta, posebno velike s mnogo tisuća redaka koda, ova vrsta dokumentacije je neprocjenjiva. Bio bi izazov naučiti o velikoj bazi koda čitajući njezin izvorni kod. Javadoc stranice čine ovaj proces mnogo bržim i lakšim za praćenje.

Javadoc vam može pomoći da vaš Java kod i svu relevantnu dokumentaciju bude organiziran i jednostavan za korištenje. Bilo da to radite za svoju zaboravnu budućnost ili da biste olakšali stvari velikom timu, Javadoc je moćan alat koji može promijeniti način na koji pišete i komunicirate s vašim Java kodiranjem projekti.

8 najboljih Java blogova za programere

Pročitajte dalje