Java'da Javadoc

Bir metodu ozel bir yorumla belgeleyin ki okuyucular ve araclar ne aldigini ve ne dondurdugunu gorsun. Yard.java icinde int x ve int y alan, toplami donduren bir add metodu yazin. /** */ blogunu dogrudan add ustune koyun. Blogun icinde isi bir kisa cumleyle anlatin, sonra her parametreyi @param ile ve sonucu @return ile etiketleyin. main icinde add(10, 2) yazdirin. javac Yard.java ile derleyin ve java Yard calistirin. Ekran 12 gostermelidir. Adlandirma kurallarini sonraki sayfaya birakin — bu ders belgeleme yorumunun sekli, isim secmek degil.

/** blogunu metodun ustune koyun

Debugging sayfasi yanlis toplami bulmak icin degerleri yazdirdi. Bu sayfa temiz bir metodun ustune belgeleme yorumu yazar. Yard.java dosyasini acin. Public sinif adini Yard tutun. Belgeleme hikayesini gomen kalan println debug etiketlerini, kalan equals / == demolari, kalan Machine horn dosyalarini ve herhangi bir klavye Scanner satirini silin. Program yazma beklememelidir. Bu demo icin import satiri gerekmez.
Yard icinde kucuk bir metot ve kisa bir main tutun. Belgeleme blogu, tarif ettigi metodun hemen ustunde oturmali. Kapanis */ ile metot satiri arasinda bos bir satir olabilir. Blogu main icine gizlemeyin. Blogu metot govdesinin altina koymayin.
Yorumun acilisini slash'tan sonra iki yildizla yazin:
/**
Sonra add in ne yaptigini soyleyen duz bir cumle yazin. Sonra etiketleri yazin. Sununla kapatin:
*/
Metotun kendisi siradan Java kalir:
static int add(int x, int y) {
return x + y;
}
Javadoc, return un nasil calistigini degistirmez. Okuyucuya, govdenin her satirini okumadan once metodun ne soz verdigini soyler.

Yard.java dosyasinin bulundugu klasorden javac Yard.java calistirin. Parantezler, suslu parantezler ve noktali virguller uyusunca javac kendi satirini yazmaz. Sonra java Yard calistirin — java Yard.java degil. Calistirma komutundan .java uzantisini birakin. Dosyada tek public sinif tutun boylece ad Yard ile eslesir.
Ekran 12 gosterir. Calismayi bir kez adim adim izleyin. Java Yard.main ile baslar. add(10, 2) cagrisi metoda girer; x onda, y ikide tutulur. return satiri on ikiyi geri verir. System.out.println o sayiyi yazar. Javadoc blogu kendi basina yazdirmaz. Blok okuyucular ve belgeleme araclari icindir. Bu sayfadaki baslangic kaniti, net bir yorumdan sonra hâlâ dogru bir calistirmadir.
Yorum blogunu okurken metot imzasina bakin. Adds two numbers. cumlesi return x + y; isiyle uyusur. @param x first number satiri ilk parametreyi adlandirir. @param y second number satiri ikinci parametreyi adlandirir. @return the sum of x and y satiri sonucu adlandirir. Etiket yazimini tam tutun: @param ve @return @ isareti ve Latin harfler kullanir.
Hâlâ bir debugging dosyasindan x=10 ve y=2 sonra 8 goruyorsaniz Javadoc ogretim dosyasina gecin ve java Yard i yeniden calistirin. Metodun ustune yalnizca // Adds two numbers. yazarsaniz siradan bir satir yorumu yazdiniz, Javadoc blogu degil. Cift yildizli /** formunu tutun boylece blok belgeleme olur, tek satirlik not olmaz.
Ekrani izlerken kurali sesli soyleyin: metodun ustunu belgeleyin, parametreleri etiketleyin, donusu etiketleyin, sonra derleyip calistirarak metodun hâlâ calistigini kanitlayin. Bu sayfada uzun adlandirma dersleri uydurmayin. Adlandirma sonraki dersi bekler.

Etiket haritasini okuyun

Kisa bir tablo, yorumda yazdiginiz uc parcayi tutar. Acilis /** */ bir belgeleme blogunu isaretler. @param bir parametre adini aciklar. @return metodun geri verdigi degeri aciklar. Metot adini add ve cagriyi add(10, 2) tutun boylece ekran tek net sayi kalsin.
Tablo bu sayfanin kisa haritasidir. Once blogu yerlestirirsiniz. Sonra girdileri ve ciktiyi etiketlersiniz. Sonra javac ve java Yard ile dogrularsiniz. Her yorum stilinin Javadoc oldugunu tahmin etmeyi atlayin. Programin hâlâ 12 bastigini bilmeden once blogu silmeyi atlayin.

Duzenlerken tabloyu ogretim dosyasinin yaninda tutun. Dosyada @param x e isaret edin, sonra imzada int x e. @param y ye isaret edin, sonra int y ye. @return e isaret edin, sonra return satirina. Bu eslestirme oyunu baslangic fikrinin tamamini tek geciste verir. Javadoc okuyan araclar bu etiketleri arar. Insan okuyucular metot govdesi sonra buyuyunce ayni haritayi kullanir.
Yakinlarda kalan debugging demolari varsa onlari tarih olarak tutun. Bu ders icin Javadoc ogretim dosyasini calistirin boylece ekran add den 12 gosterir, avdan gelen etiketli x= satirlari degil. javac yinelenen public siniflardan sikayet ederse yalnizca Yard i public tutun.

Siradan // Javadoc degildir

// ile baslayan bir satir, dosyayi okuyan biri icin bir nottur. Faydalidir ve bu kurs daha once satir yorumlarini kullanmistir. Bu sayfanin ogrettigi belgeleme blogu sekli degildir. Bir metot icin Javadoc /** ile baslar ve */ ile biter. @param ve @return etiketleri o blogun icinde oturur.
Metottan sonra baska ifadelerin altina duz bir string koyarsaniz, o string metot belgelemesi olmaz. Belgeleme blogu metoda yapisan, ustteki yorum olmalidir. Blogu add e yakin tutun. main i sahte belgeleme tiyatrosundan uzak tutun. main icindeki cagri, donen toplamin normal yazdirmasi kalir.
Yorum yanlis ama metot govdesi dogruysa javac yine basarili olabilir ve java Yard yine 12 basabilir. Bu yuzden bu sayfa yorumu ve imzayi birlikte okumanizi ister, yalnizca ekrani degil. Ekran matematigi kanitlar. Yorum sozlesmeyi etiketlediginizi kanitlar.

Debugging yazdirmalariyla karsilastirma

Debugging sayfasinda println, toplam yanlis gorunurken sayilarinizin gercekten ne olduguna yanit verdi. Bu sayfada Javadoc, okuyucu govdeye dalmadan once add in ne soz verdigine yanit verir. Hâlâ Yard.java derler ve java Yard calistirirsiniz. Yeni isaretler bir metodun ustundeki /**, @param ve @return dir.
Debugging siradan ciktiyi fener gibi kullandi. Javadoc yapilandirilmis bir yorumu metot kapisinin etiketi gibi kullanir. Etiket parametreler ve donusle uyusunca okuyucular daha az tahmin eder. Etiket eksikken program hâlâ calisabilir — belgeleme aliskanligi yine eksiktir.
Hâlâ bir debugging dosyasi aciksa x=10, y=2 ve eski bir toplam gorebilirsiniz. main add(10, 2) yazdirsin ve metot belgeleme blogunu tasisin diye Javadoc dosyasina gecin. Adlandirma tarzi derslerini bu sayfanin disinda tutun. Klavye girisini bu sayfanin disinda tutun.

Adlandirmadan once

/** */ yi add ustune koyabilir, @param x, @param y, @return etiketleyebilir ve java Yard dan sonra hâlâ 12 gorebilirsiniz. Tutulan demo icin Yard.java derleyin ve java Yard calistirin. Yorum okuyuculara sozlesmeyi soyledi. Sonraki sayfa adlandirmadir; orada yazdiklariniz icin net isimler secersiniz.
Belgelenmis add demosunu net bir yorum-arti-calistirma cifti icin tutun. Belgeleme pratigi yaparken debugging dosyalarini bu sayfanin disinda tutun. Adlandirma dosyalarini o ders gelene kadar bu sayfanin disinda tutun. Bu uc aliskanlik ilerlemeden onceki kontrol noktasidir. Etiketler imzayla uyusunca ve ekran 12 gosterince Javadoc bu dersin isini yapmistir ve adlandirma hakkındaki sonraki konuya hazirsiniz.
Klasorden son bir gecis: bir public Yard, bir belgelenmis add, main de bir yazdirma, klavye beklemesi yok, zorla adlandirma kurali yok. Acik tuttugunuz demoda bir kez daha javac Yard.java ve java Yard calistirin. Ekran hâlâ 12 gosteriyorsa ve yorum hâlâ add ustunde @param ve @return ile oturuyorsa belgeleme sekli saglamdir ve kurs sonraki sayfada adlandirmaya gecebilir. Her okuma ayni haritayi ogretsin diye bir metotta tek net belgeleme blogunu tercih edin.