Samodejno dokumentirajte svojo kodo Java z Javadoc

Če se ukvarjate s kakršnim koli programiranjem, se boste dobro zavedali, da je ena izmed najbolj dolgočasnih nalog dokumentiranje vaše kode. Ne glede na to, ali se vam zdi to rahlo nadležno ali podvig, s katerim se soočate z absolutnim strahom, je dokumentacija kode bistvenega pomena. Drugi morajo razumeti, kako deluje vaša koda, vi pa ste morda celo eden izmed njih, če jo boste brali pozneje!

Java priročno ponuja vgrajeno rešitev problema: Javadoc.

Javadoc vam lahko pomaga samodejno dokumentirati kodo

Upajmo, da že sledite dobre prakse kodiranja in v svojo kodo vključite pojasnjevalne komentarje. Čeprav je ta vrsta komentiranja v kodi vsekakor koristna, v resnici ne zagotavlja ničesar primerljivega s priročnikom.

Seveda lahko drug programer pregleda vašo kodo in prebere o posebnih razredih, metodah in funkcijah, ki so pred njim. Vendar je izjemno težko dobiti dober pregled nad vso kodo ali najti funkcije, ki bi lahko bile uporabne, če ne veste, da obstajajo. Javadoc želi rešiti ta problem.

Javadoc bo samodejno ustvaril podroben in bralcu prijazen priročnik HTML za vso vašo kodo. Najboljše od vsega je, da to stori z uporabo komentarjev kode, ki jih verjetno že pišete.

Kaj pravzaprav je Javadoc in kako deluje?

Javadoc je samostojen program, ki prihaja v paketu z izdajami Oraclovega razvojnega kompleta Java (JDK). Pravzaprav ga ne morete prenesti ločeno. Ko prenesete in namestite eno od Oraclovih različic JDK, bo namestil tudi Javadoc.

Ko ga zaženete, Javadoc ustvari dokumentacijo HTML iz posebej oblikovanih komentarjev v vaši izvorni kodi Java. Ta postopek ustvarja bolj uporabno in berljivo dokumentacijo, hkrati pa spodbuja najboljše prakse.

Na kratko, Javadoc vam omogoča, da hkrati napišete svojo kodo in njeno dokumentacijo. Poenostavlja vaš potek dela in vam omogoča učinkovitejšo izrabo časa.

Javadoc deluje tako, da razčleni posebej oblikovane komentarje v vaši kodi in jih pretvori v izhod HTML. Edina sprememba, ki jo resnično morate narediti, je vključiti določene nize v svoje komentarje. Te sporočajo Javadocu, kaj želite vključiti v končno dokumentacijo.

Komentarji Javadoc morajo biti neposredno pred izjavo razreda, polja, konstruktorja ali metode. Sam komentar bi moral:

• Začnite s tremi liki /**.
• Vključite zvezdico na začetek vsake nove vrstice.
• Zaprite z dvema znakoma */.

Znotraj komentarjev lahko v končni rezultat vključite HTML in vključite oznake, ki bodo ustvarile povezave do ustreznih delov vaše kodne baze. Za vključitev slik v končno dokumentacijo lahko uporabite celo stvari, kot so slikovne oznake HTML. Ko se navadite na obliko in razpoložljive oznake, je pisanje takšnih komentarjev enostavno.

Tukaj je primer za ponazoritev preprostih komentarjev Javadoc, ki opisujejo funkcijo, ki pridobi sliko iz URL-ja in jo natisne na zaslon. Komentar je neposredno pred funkcijo in opisuje, kaj počne. Ta blok komentarjev uporablja tudi tri oznake, specifične za razdelek: @param, @vrni se, in @glej.

/**
* Vrne slikovni predmet, ki ga je mogoče nato naslikati na zaslonu.
* Argument url mora podajati absolutno vrednost {@povezava URL}. Ime
* argument je specifikator, ki je sorazmeren z argumentom url.
* 

* Ta metoda se vedno vrne takoj, ne glede na to, ali je
* slika obstaja. Kdaj to applet poskuša narisati sliko
* na zaslonu se bodo podatki naložili. Grafični primitivi
*, ki narišejo sliko, bodo postopoma slikali na zaslonu.
*
* @param url absolutni URL, ki daje osnovno lokacijo slike
* @param poimenujte lokacijo slike glede na argument url
* @vrni se sliko na določenem URL-ju
* @glej Slika
*/
javnosti Slika getImage(URL URL, ime niza){
poskusi {
vrnitev getImage(novo URL (url, ime));
 } ujeti (Napačno oblikovanaURLEException e) {
vrnitevnič;
 }
}

Ko Javadoc obdela zgornjo kodo, ustvari spletno stran, podobno naslednji:

Brskalnik upodablja izhod Javadoc na skoraj enak način, kot prikazuje kateri koli dokument HTML. Javadoc prezre dodatne presledke in prelome vrstic, razen če za ustvarjanje tega prostora uporabite oznake HTML.

Oznake @, uporabljene na koncu komentarja, ustvarijo Parametri, Vrne, in Poglej tudi odsekov, ki jih vidite.

Morali bi slediti @param oznako z imenom parametra, presledkom in njegovim opisom. V zgornjem primeru sta dva parametra: url in ime. Upoštevajte, da sta oba prikazana pod istim naslovom Parameter v izhodu dokumentacije. Navedete lahko toliko parametrov, kolikor je potrebnih za funkcijo ali metodo, ki jo opisujete.

The @vrni se tag dokumentira vrednost, ki jo funkcija vrne, če sploh. Lahko je preprost enobesedni opis ali več stavkov, odvisno od okoliščin.

The @glej tag vam omogoča, da označite druge funkcije, ki so povezane ali pomembne. V tem primeru se oznaka @see nanaša na drugo funkcijo, imenovano preprosto Slika. Upoštevajte, da so reference, narejene s to oznako, povezave, ki jih je mogoče klikniti, kar bralcu omogoča, da skoči na navedeni element v končnem HTML-ju.

Na voljo je več oznak, kot so @version, @author, @exception in druge. Ko se pravilno uporabljajo, oznake pomagajo povezati elemente med seboj in omogočajo enostavno krmarjenje po dokumentaciji.

Zagon Javadoc na vaši izvorni kodi

Javadoc pokličete v ukazni vrstici. Zaženete ga lahko v posameznih datotekah, celotnih imenikih, paketih Java ali na seznamu posameznih datotek. Javadoc bo privzeto ustvaril dokumentacijske datoteke HTML v imeniku, kamor vnesete ukaz. Če želite dobiti pomoč pri določenih ukazih, ki so na voljo, preprosto vnesite:

javadoc --pomoč

Če želite podrobneje videti, kaj lahko naredi Javadoc, si oglejte uradno dokumentacijo iz Oracle. Če želite ustvariti hiter nabor dokumentacije za eno datoteko ali imenik, lahko vnesete javadoc v ukazni vrstici, ki ji sledi ime datoteke ali nadomestni znak.

javadoc ~/code/ime datoteke.java
javadoc ~/code/*.java

Zgoraj je seznam datotek in imenikov, ki jih je ustvaril Javadoc. Kot vidite, jih je kar nekaj. Iz tega razloga morate biti prepričani, da niste v istem imeniku kot izvorna koda, ko zaženete program. S tem bi lahko ustvarili precej nered.

Če si želite ogledati novo ustvarjene dokumente, preprosto odprite index.html datoteko v želenem brskalniku. Dobili boste stran, kot je naslednja:

To je dokumentacija za en sam, kratek razred Java, ki prikazuje izhod. V glavi je prikazano ime razreda in metode, ki so v njem vključene. Pomikanje navzdol razkrije podrobnejše definicije vsake metode razreda.

Kot lahko vidite, je ta vrsta dokumentacije neprecenljiva za vse vrste projektov Java, še posebej velike z več tisoč vrsticami kode. Izziv bi bil spoznati veliko zbirko kod z branjem njene izvorne kode. Strani Javadoc naredijo ta proces veliko hitrejši in lažje slediti.

Javadoc vam lahko pomaga ohranjati vašo kodo Java in vso ustrezno dokumentacijo organizirano in enostavno za uporabo. Ne glede na to, ali to počnete za svojo pozabljivo prihodnost ali da olajšate stvari veliki ekipi, Javadoc je zmogljivo orodje, ki lahko spremeni način pisanja in interakcije z vašim kodiranjem Java projekti.

8 najboljših blogov Java za programerje

Preberite Naprej