Java Kodunuzu Javadoc ile Otomatik Olarak Belgeleyin

Herhangi bir tür programlama yaparsanız, ilgili en sıkıcı görevlerden birinin kodunuzu belgelemek olduğunu bilirsiniz. İster biraz can sıkıcı buluyor olun, ister mutlak bir korkuyla karşı karşıya kaldığınız bir girişim olsun, kod dokümantasyonu çok önemlidir. Diğerlerinin kodunuzun nasıl çalıştığını anlaması gerekir ve daha sonraki bir tarihte okuyorsanız, onlardan biri bile olabilirsiniz!

Java, soruna uygun bir şekilde yerleşik bir çözüm sağlar: Javadoc.

Javadoc, Kodunuzu Otomatik Olarak Belgelemenize Yardımcı Olabilir

İnşallah zaten takip edersin iyi kodlama uygulamaları ve kodunuza açıklayıcı yorumlar ekleyin. Bu tür kod içi yorumlar kesinlikle yararlı olsa da, bir kılavuzla karşılaştırılabilir hiçbir şey sağlamaz.

Elbette, başka bir programcı kodunuza bakabilir ve önündeki belirli sınıfları, yöntemleri ve işlevleri okuyabilir. Bununla birlikte, kodun tümüne iyi bir genel bakış elde etmek veya var olduklarını bilmediğiniz durumlarda yararlı olabilecek işlevleri bulmak son derece zordur. Javadoc bu sorunu çözmeyi amaçlıyor.

Javadoc, tüm kodunuz için otomatik olarak ayrıntılı ve okuyucu dostu bir HTML kılavuzu oluşturacaktır. Hepsinden iyisi, bunu muhtemelen zaten yazdığınız kod yorumlarını kullanarak yapar.

Javadoc Tam Olarak Nedir ve Nasıl Çalışır?

Javadoc, Oracle'ın Java geliştirme kiti (JDK) sürümleriyle birlikte gelen bağımsız bir programdır. Aslında, ayrı olarak indiremezsiniz. İndirdiğinizde ve Oracle'ın JDK sürümlerinden birini yükleyin, Javadoc'u da yükleyecektir.

Çalıştırdığınızda, Javadoc, Java kaynak kodunuzdaki özel olarak biçimlendirilmiş yorumlardan HTML belgeleri oluşturur. Bu süreç, en iyi uygulamaları teşvik ederken daha kullanışlı, okunabilir belgeler oluşturur.

Özetle Javadoc, kodunuzu ve belgelerini aynı anda yazmanıza olanak tanır. İş akışınızı basitleştirir ve zamanınızı daha verimli kullanmanızı sağlar.

Javadoc, kodunuzdaki özel olarak biçimlendirilmiş yorumları ayrıştırarak ve bunları HTML çıktısına dönüştürerek çalışır. Gerçekten yapmanız gereken tek değişiklik, yorumlarınıza belirli dizeleri eklemektir. Bunlar, Javadoc'un nihai belgelere ne eklemek istediğinizi bilmesini sağlar.

Javadoc yorumları bir sınıf, alan, kurucu veya yöntem bildiriminden hemen önce gelmelidir. Yorumun kendisi şunları yapmalıdır:

• Üç karakterle başlayın /**.
• Her yeni satırın başına bir yıldız işareti ekleyin.
• İki karakterle kapat */.

Yorumların içinde, nihai çıktıya HTML ekleyebilir ve kod tabanınızın ilgili bölümlerine bağlantılar oluşturacak etiketleri dahil edebilirsiniz. Görüntüleri nihai belgelere dahil etmek için HTML görüntü etiketleri gibi şeyleri bile kullanabilirsiniz. Biçime ve mevcut etiketlere alıştıktan sonra, bu tür yorumları yazmak çok kolay.

Bir URL'den bir görüntü alan ve ekrana yazdıran bir işlevi açıklayan basit Javadoc yorumlarını gösteren bir örnek. Yorum, işlevden hemen önce gelir ve ne yaptığını açıklar. Bu yorum bloğu ayrıca bölüme özel üç etiket kullanır: @param, @dönüş, ve @görmek.

/**
* Daha sonra ekrana boyanabilecek bir Görüntü nesnesi döndürür.
* url bağımsız değişkeni mutlak bir değer belirtmelidir {@bağlantı URL}. İsim
* argümanı, url argümanına göre bir belirteçtir.
* 

* Bu yöntem her zaman anında döner.
* görüntü var. Ne zaman Bu uygulama görüntüyü çizmeye çalışır
* Ekrana veriler yüklenecektir. Grafik ilkelleri
* resmi çizen kişi ekranı kademeli olarak boyayacaktır.
*
* @param url resmin temel konumunu veren mutlak bir URL
* @param url argümanına göre görüntünün konumunu adlandırın
* @dönüş belirtilen URL'deki resim
* @görmek resim
*/
halka açık resim Görüntü almak(URL url'si, Dize adı){
denemek {
dönüş Görüntü almak(yeni URL(url, isim));
 } tutmak (MalformedURLException e) {
dönüşhükümsüz;
 }
}

Javadoc yukarıdaki kodu işlediğinde, aşağıdakine benzer bir web sayfası oluşturur:

Bir tarayıcı, Javadoc çıktısını herhangi bir HTML belgesini gösterdiği şekilde işler. Javadoc, bu alanı oluşturmak için HTML etiketlerini kullanmadığınız sürece fazladan boşlukları ve satır sonlarını yok sayar.

Yorumun sonunda kullanılan @ etiketleri, parametreler, İadeler, ve Ayrıca bakınız gördüğünüz bölümler

takip etmelisin @param parametrenin adı, bir boşluk ve bunun bir açıklaması ile etiketleyin. Yukarıdaki durumda, iki parametre vardır: url ve isim. Her ikisinin de belge çıktısında aynı Parametreler başlığı altında göründüğüne dikkat edin. Tanımladığınız işlev veya yöntem için gerekli olduğu kadar çok parametre listeleyebilirsiniz.

bu @dönüş etiketi, eğer varsa, işlevin döndürdüğü değeri belgeler. Koşullara bağlı olarak tek kelimelik basit bir açıklama veya birçok cümle olabilir.

bu @görmek etiketi, ilgili veya alakalı diğer işlevleri etiketlemenize olanak tanır. Bu durumda @see etiketi, basitçe Image olarak adlandırılan başka bir işleve atıfta bulunur. Bu etiketle yapılan referansların tıklanabilir bağlantılar olduğunu ve okuyucunun son HTML'de referans verilen öğeye atlamasına izin verdiğini unutmayın.

@version, @author, @exception ve diğerleri gibi daha fazla etiket mevcuttur. Doğru kullanıldığında, etiketler öğelerin birbiriyle ilişkilendirilmesine yardımcı olur ve belgelerde kolayca gezinmeyi mümkün kılar.

Javadoc'u Kaynak Kodunuzda Çalıştırmak

Javadoc'u komut satırında çağırırsınız. Tek dosyalarda, tüm dizinlerde, java paketlerinde veya tek tek dosyalar listesinde çalıştırabilirsiniz. Varsayılan olarak Javadoc, komutu girdiğiniz dizinde HTML dokümantasyon dosyalarını oluşturacaktır. Mevcut belirli komutlar hakkında yardım almak için şunu girin:

javadoc --Yardım Edin

Javadoc'un tam olarak neler yapabileceğini daha ayrıntılı olarak görmek için resmi belgelere bakın. kehanet. Tek bir dosya veya dizinde hızlı bir belge seti oluşturmak için şunu girebilirsiniz: javadoc komut satırında, ardından bir dosya adı veya joker karakter.

javadoc ~/code/dosyaadi.java
javadoc ~/code/*.java

Yukarıda Javadoc'un oluşturduğu dosya ve dizinlerin bir listesi bulunmaktadır. Gördüğünüz gibi, bunlardan epeyce var. Bu nedenle programı çalıştırırken kaynak kodunuzla aynı dizinde olmadığınızdan emin olmalısınız. Bunu yapmak oldukça karışıklık yaratabilir.

Yeni oluşturduğunuz dokümanları görüntülemek için index.html tercih ettiğiniz tarayıcıda dosya. Aşağıdaki gibi bir sayfa alacaksınız:

Bu, çıktıyı göstermek için tek bir kısa Java sınıfının belgeleridir. Başlık, sınıfın adını ve içinde yer alan yöntemleri gösterir. Aşağı kaydırma, sınıf yöntemlerinin her birinin daha ayrıntılı tanımlarını ortaya çıkarır.

Gördüğünüz gibi, her tür Java projesi için, özellikle binlerce kod satırı içeren büyük projeler için, bu tür belgeler paha biçilmezdir. Kaynak kodunu okuyarak büyük bir kod tabanı hakkında bilgi edinmek zor olacaktır. Javadoc sayfaları bu işlemi çok daha hızlı ve takip edilmesi daha kolay hale getirir.

Javadoc, Java kodunuzu ve ilgili tüm belgeleri düzenli ve kullanımı kolay tutmanıza yardımcı olabilir. İster unutkan gelecekteki benliğiniz için, ister büyük bir ekip için işleri kolaylaştırmak için yapıyor olun, Javadoc, Java kodlamanızla yazma ve etkileşim kurma şeklinizi değiştirebilen güçlü bir araçtır. projeler.

Programcılar için En İyi 8 Java Blogu

Sonrakini Oku