Projelerimizde yazmış olduğumuz sınıfların başkaları tarafından kolay anlaşılmasını sağlamak için kullanılan bir yapıdır. Özellikle jar haline getirilmiş APIlerin kullanımında kullanıcıyı bilgilendirmek için çok önemlidir.
JavaDoc bize dökümantasyon yazmak için bir format sunar.Bu formatta HTML etiketleri kullanılabileceği gibi JavaDoc'a ait etiketlerde mevcuttur. JavaDoc dokümantasyonunu, class, interface ya da enum tiplerinden önce, nesne ve sınıf değişkenlerinden önce ve constructorlar dahil olmak üzere metotlardan önce, /** */ formatında yazılır.
Dökümantasyonu yapılmış kodu HTML dökümantasyonu haline getirmek için jdk ile gelen javadoc aracı ile şu şekilde yapabilirsiniz.
javadoc -d documentation sınıf.java
Böylelikle sınıfımızın dokümantasyonunu "documentation" isimli bir dosyaya çıkarmış oluyoruz. Bir başka yolu kullandığınız IDE'lerin generate javadoc özelliğini kullanabilirsiniz.
JavaDoc'un etiketleri
@author -> Geliştiren kişi
@param -> Parametre tipi ve anlamı
@throws ,@exception -> İstisna durumları ve anlamları
@return -> Dönüş tipi
@see -> Başka bir yere referans sağlar
@since -> Hangi sürüm ile eklendiği
@version -> Son güncellendiği sürüm
{@code} -> Kodu belirtmek için
@deprecated -> Artık kullanılmaması istemi
{@value} -> Statik alanın doc açıklamada kullanıldığı zaman, o sabitin değerini gösterir.
{@link} -> Başvurulan sınıfın belirtilen paket, sınıf veya üye adı belgelere işaret görünür .
{@linkplain} -> Bağlantının etiketine hariç {@link}, Özdeş kod yazı daha düz metin olarak görüntülenir.
@serial -> Varsayılan serializable alan için doc yorumda kullanılır.
@serialData -> writeObject () veya writeExternal tarafından yazılmış verileri belgelemektedir
@serialField -> Bir ObjectStreamField bileşeni belgelemektedir.
{@inheritDoc} -> En yakın kalıtsal sınıf veya uygulanabilir arayüz gösterir.
{@docRoot} -> Üretilen her sayfa üretilen belgenin kök dizinine göre yolunu gösterir.
{@literal} -> literal metni belirtir. kapalı metin, HTML biçimlendirme veya iç içe javadoc etiketleri içermeyen olarak yorumlanır.
Küçük bir örnek ise şöyle verilebilir.
/**
* Merhaba, Dünya!
* Bu program javaya ilk başladığımızda yazacağımız programdır.
* Çıktı olarak konsol ekranına Merhaba,Dünya! yazar.
*
*
* @author Eren Çetinkaya Cruz
* @version 1.0
* @since 2016-03-24
*/
public class HelloWorld {
public static void main(String[] args) {
System.out.println("Hello World!");
}
} Alışkanlık edinmek JavaDoc'u bundan sonraki yazılarımda kullanmaya çalışacağım.
Daha detaylı olarak JavaDoc resmi sitesinden öğrenebilirsiniz.
Başka bir kaç yer ingilizce olarak tutorialpoints veya türkçe olarak Akin Kaldiroglu hocamızın yazılarından faydalanabilirsiniz.