Dokumentovanje koda - javadoc i distribucija programa - JAR

Bojan Tomi

Vrste dokumentacije

Projektna dokumentacija

Korisniki zahtev ema baze podataka Razni UML dijagrami (dijagrami klasa, sekvenci, aktivnosti...) Korisniko uputstvo komentari javadoc

Dokumentacija u okviru koda

Komentari

Obino se piu u okviru tela metode da objasne pojedine naredbe u kodu

Jednolinijski komentar //Jednolinijski komentar

Vielinijski komentar /* Viselinijski

komentar */

Komentari

Prednosti

Jednostavno i brzo dokumentovanje pojedinih delova koda Dokumentacija se nalazi u okviru koda pa je odmah dostupna Nisu dobri za dokumentovanje celih metoda ili klasa jer se teko slae tekst Nemaju nikakvu unutranju strukturu Ne mogu se videti van izvornog koda

Nedostaci

Ideja

Napraviti mehanizam koji e da iskoristi sve prednosti komentara i da otkloni njihove nedostatke Ovaj mehanizam bi trebalo da:

Bude jednostavan za korienje Omoguava unoenje dokumentacije uz kod (radi lakeg odravanja) Obezbeuje neku strukturu Omoguava itanje dokumentacije i bez izvornog koda

javadoc

Standard za dokumentovanje Java koda javadoc alati su deo JDK instalacije Koristi specijalne komentare iz koda Izvlai komentare tako da mogu da se vide i bez izvornog koda Pretvara komentare u HTML koji se prikazuje korisniku (JSE API je u stvari javadoc) Eclipse i NetBeans imaju ugraenu podrku za javadoc

javadoc - sintaksa

javadoc dokumenti su specijalni komentari Ovi komentari poinju znacima /** a zavravaju se znacima */

Svaki red moe da pone zvezdicom * ali ne mora /**

* javadoc dokument - komentar */

javadoc - sintaksa

javadoc komentari se mogu pisati:

tano iznad deklaracije klase (dokumentovanje klase) tano iznad deklaracije atributa (dokumentovanje atributa) tano iznad deklaracije metode (dokumentovanje metoda)

Komentari za public i protected elemente se vide van fajla (moe i za private ako se tako naznai)

javadoc - sintaksa

Primer

/** Dokumentacija klase */ public class DokumentovanaKlasa { /** Dokumentacija atributa1 */ public int atribut1; /** Dokumentacija metode1 */ public int metoda1(){return 0;} }

javadoc - sintaksa

javadoc tagovi - posebne oznake kojima se uvodi struktura u dokumente Svaki tag poinje znakom @ Tagovi su opcioni i ne moraju se navesti

Tag mora da se pie na poetku reda /** * @author Bojan Tomic */

javadoc - sintaksa
javadoc komentar moe da sadri i HTML /**

* <ul> * <li>Prva stavka * <li>Druga stavka * </ul> */

javadoc - tagovi

@author informacije_o_autoru

Oznaava autora klase (iil nekog njenog dela) Moe se navesti vie author tagova (ako klasa ima vie autora ili ako se prikazuju dodatne informacije) ali moraju biti tano jedan ispod drugog Oznaava bilo kakve znaajne informacije o verziji klase, metode isl.

@version informacije_o_verziji

javadoc - tagovi

@param naziv_parametra opis

Oznaava informacije o ulaznom parametru metode Koristi se iskljuivo za dokumentaciju metoda Prvo se pie naziv parametra pa u produetku njegov opis Trebalo bi napisati po jedan tag za svaki ulazni parametar Tekst ovog taga se zavrava tek kada se naie na sledei tag

javadoc - tagovi

@return opis_povratne_vrednosti_metode

Oznaava informacije povratnoj vrednosti metode (ako metoda neto vraa) Koristi se iskljuivo za dokumentaciju metoda Tekst ovog taga se zavrava tek kada se naie na sledei tag

javadoc - tagovi

@throws pun_naziv_klase_izuzetka opis

Oznaava informacije o izuzetku koji metoda baca Koristi se iskljuivo za dokumentaciju metoda Prvo se pie pun naziv klase izuzetka (zajedno sa nazivom paketa kojem pripada) pa se u produetku daje opis situacije u kojoj metoda baca izuzetak Ako metoda baca vie vrsta izuzetaka, pie se po jedan tag za svaku vrstu Tekst ovog taga se zavrava tek kada se naie na sledei tag

Distribucija programa - JAR

JAR - Java ARchive Platformski nezavisni fajlovi pogodni za distribuciju programa (ekstenzija *.jar) Zapravo ZIP fajlovi Sadre sve to ini jedan program ili biblioteku

Sve pakete sa .class fajlovima Sve dodatne resurse tipa slike, ikonice, tekstualni fajlovi itd. Manifest (u njemu moe da stoji i koja je klasa zaduena za pokretanje programa)

Distribucija programa - JAR

Pokretanje programa duplim klikom mia (executable JAR file) Dovoljno je dodati taj JAR fajl na CLASSPATH da bi se koristile klase u njemu Eclipse i NetBeans imaju ugraenu podrku za JAR