Menü

JavaDoc Nedir ve Belge Oluşturmak İçin Nasıl Kullanılır

  • Ana
  • Diğer
  • JavaDoc Nedir ve Belge Oluşturmak İçin Nasıl Kullanılır

what is javadoc how use it generate documentation

Sorunları Ortadan Kaldırmak Için Enstrümanımızı Deneyin

Bu eğitici, JavaDoc aracının ve JavaDoc Açıklamalarının ne olduğunu ve kod belgeleri oluşturma yöntemlerini açıklar:

JavaDoc, JDK ile paketlenmiş özel bir araçtır. Java kaynak kodunun kod belgelerini HTML biçiminde oluşturmak için kullanılır.

Sun Microsystems'den (şu anda Oracle Corporation) Java dili için bir dokümantasyon oluşturucusudur.

=> TÜM Java Öğreticilerini Buradan Kontrol Edin.

JavaDoc aracı

Ne öğreneceksin:

JavaDoc nedir

Bu araç, Java sınıflarını belgelemek için 'belge yorumları' biçimini kullanır. Eclipse, IntelliJIDEA veya NetBeans gibi IDE'ler, HTML belgeleri oluşturmak için yerleşik bir JavaDoc aracına sahiptir. Ayrıca piyasada programcının JavaDoc kaynaklarını üretmesine yardımcı olabilecek birçok dosya düzenleyicimiz var.

Bu araç, kaynak kodu dokümantasyonunun yanı sıra, bir Java uygulamasının yapısını analiz etmek için kullandığımız “dokümanlar” ve “etiketler” oluşturan API de sağlar.

Dikkat edilmesi gereken bir nokta, bu aracın, derleyici Java programının derlenmesi sırasında tüm yorumları kaldırması nedeniyle uygulamanın performansını hiçbir şekilde etkilememesidir.

Programa yorum yazmak ve ardından belgeleri oluşturmak için JavaDoc kullanmak, programcının / kullanıcının kodu anlamasına yardımcı olmaktır.

JavaDoc tarafından oluşturulan HTML belgeleri, API belgeleridir. Bildirimleri ayrıştırır ve bir dizi kaynak dosyası oluşturur. Kaynak dosya alanları, yöntemleri, yapıcıları ve sınıfları tanımlar.

JavaDoc aracını kaynak kodumuzda kullanmadan önce, programa özel JavaDoc yorumları eklememiz gerektiğini unutmayın.

Şimdi yorumlara geçelim.

JavaDoc Yorumları

Java dili, aşağıdaki türden yorumları destekler.

# 1) Tek satır yorumlar: Tek satırlık yorum ' // ”Ve derleyici bunlarla karşılaştığında, bu yorumları satırın sonuna kadar takip eden her şeyi yok sayar.

# 2) Çok satırlı yorumlar: Çok satırlı yorumlar ' /*….*/ ”. Dolayısıyla, '/ *' dizisiyle karşılaşıldığında, derleyici '* /' kapanış dizisi ile karşılaşana kadar bu diziyi izleyen her şeyi yok sayar.

# 3) Dokümantasyon yorumları: Bunlara Doküman yorumları denir ve araç tarafından API dokümantasyonu oluşturmak için kullanılır. Doküman yorumları ' / ** belgeler * / ”. Gördüğümüz gibi, bu yorumlar yukarıda açıklanan normal yorumlardan farklıdır. Doküman yorumları, kısaca göreceğimiz gibi içlerinde HTML etiketleri de içerebilir.

ana python'da bir işlev nasıl çağırılır

Dolayısıyla, bu aracı kullanarak API belgeleri oluşturmak için, programımızda bu belge yorumlarını (belge yorumları) sağlamalıyız.

JavaDoc Yorumunun Yapısı

Java'daki Doc yorumunun yapısı, doküman yorumunun açılış etiketinde fazladan bir yıldız işaretine (*) sahip olması dışında çok satırlı yoruma benzer. Dolayısıyla, doküman yorumu '/ *' yerine '/ **' ile başlar.

Ek olarak, JavaDoc tarzı yorumların içinde HTML etiketleri de olabilir.

JavaDoc Yorum Biçimi

Belgelemek istediğimiz programlama yapısına bağlı olarak, belge yorumlarını sınıf, yöntem, alan vb. Gibi herhangi bir yapının üzerine yerleştirebiliriz. Şimdi yapıların belge yorumlarının her birinin örneklerinden geçelim.

Sınıf Düzeyi Formatı

Sınıf düzeyindeki belge yorum biçimi aşağıda gösterildiği gibi görünecektir:

/** * Mechanic * * Please see the {@link sth.javadoctutes.Person} class for true identity * @author SoftwareTestingHelp * */ public class Mechanic extends Person { // fields and methods }

Yukarıda gösterildiği gibi, sınıf düzeyinde bir belge yorumu, sınıfın yazarı, varsa bağlantılar vb. Dahil tüm ayrıntılara sahip olacaktır.

Yöntem Seviye Biçimi

Aşağıda, yöntem düzeyinde bir doc biçimi örneği verilmiştir.

/** *

simple method description … * JavaDoc! *

* @param msg the message to be printed * @return void * @see JavaDoc * @since 2.0 */ public void printMessage (String msg) { // do things return 0; }

Yukarıdaki örnekten de görebileceğimiz gibi, yöntemin doc yorumunda herhangi bir sayıda etiketimiz olabilir. Ayrıca, ile belirtilen yorum açıklamasının içinde paragraflar da olabilir.

...

.

Ayrıca, dönüş değerini (@return) ve yöntemin (@param) parametrelerini açıklayan özel etiketlerimiz var.

Alan Düzeyi Biçimi

Aşağıdaki örnek, bir alan için belge açıklamasını gösterir.

/** * The public name of a message */ private String msg_txt;

Yukarıdaki örnekte görüldüğü gibi, herhangi bir etiket olmadan da düz yorumlarımız olabilir. JavaDoc komutuyla özel bir seçenek belirtmedikçe, JavaDoc'un özel alanlar için herhangi bir belge oluşturmadığını unutmayın.

Şimdi doküman yorumlarında kullanılan etiketleri tartışalım.

JavaDoc Etiketleri

Java, belge yorumuna ekleyebileceğimiz çeşitli etiketler sağlar. Bu etiketleri kullandığımızda araç, kaynak koddan iyi biçimlendirilmiş bir API oluşturmak için bu etiketleri ayrıştırır.

Her etiket büyük / küçük harfe duyarlıdır ve '@' işaretiyle başlar. Yukarıdaki örneklerden de görebileceğimiz gibi her etiket satırın başında başlar. Aksi takdirde, derleyici bunu normal bir metin olarak değerlendirir. Bir kural olarak, aynı etiketler birlikte yerleştirilir.

Doküman yorumunda kullanabileceğimiz iki tür etiket vardır.

# 1) Etiketleri Engelle : Blok etiketleri şu şekildedir: @etiket adı .

Blok etiketleri, etiket bölümüne yerleştirilebilir ve ana açıklamayı takip edebilir .

# 2) Satır İçi Etiketler :Satır içi etiketler süslü parantez içine alınır ve biçimindedir, {@etiket adı} . Satır içi etiketler, belge yorumunun içinde herhangi bir yere yerleştirilebilir.

Aşağıdaki tablo, belge yorumlarında kullanılabilecek tüm etiketleri listeler.

android'de apk dosyaları nasıl açılır
EtiketAçıklamaİçin geçerlidir
@return açıklamasıDönüş değeri açıklaması sağlar.Yöntem
@yazar xyzSınıf, arabirim veya numaralandırmanın yazarını gösterir.Sınıf, Arayüz, Enum
{@docRoot}Bu etiket, belgenin kök dizinine giden göreceli yola sahiptir.Sınıf, Arabirim, Enum, Alan, Yöntem
@version sürümüYazılım sürümü girişini belirtir.Sınıf, Arayüz, Enum
@since beri-textBu işlevselliğin ne zamandan beri var olduğunu belirtirSınıf, Arabirim, Enum, Alan, Yöntem
@ bkz. referansDiğer belgelere referansları (bağlantıları) belirtirSınıf, Arabirim, Enum, Alan, Yöntem
@param adı açıklamasıYöntem parametresini / bağımsız değişkenini açıklamak için kullanılır.Yöntem
@exception sınıf adı açıklamasıYöntemin kodunda oluşturabileceği istisnayı belirtir.Yöntem
@ sınıf adı açıklamasını atar
@deprecated açıklamaYöntemin güncel olup olmadığını belirtirSınıf, Arabirim, Enum, Alan, Yöntem
{@inheritDoc}Kalıtım durumunda açıklamayı geçersiz kılınan yöntemden kopyalamak için kullanılırGeçersiz Kılma Yöntemi
{@link referansı}Diğer sembollere referanslar veya bağlantılar sağlar.Sınıf, Arabirim, Enum, Alan, Yöntem
{@linkplain referansı}{@Link} ile aynıdır ancak düz metin olarak görüntülenir.Sınıf, Arabirim, Enum, Alan, Yöntem
{@value #STATIC_FIELD}Statik bir alanın değerini açıklayın.Statik Alan
{@code literal}{@Literal} benzeri kod yazı tipinde değişmez metni biçimlendirmek için kullanılır. Class, Interface, Enum, Field, Method
{@literal literal} Indicates literal text. the enclosed text is interpreted literally without any style formatting.Class, Interface, Enum, Field, Method
{@serial literal} Description of a serializable field. Field
{@serialData literal} Documents the data written by the writeExternal( ) or writeObject( ) methods. Field, Method
{@serialField literal} Describes an ObjectStreamField component. Field

Generate Java Doc

To create a JavaDoc you do not need to compile the Java file. We can generate JavaDoc documentation in two ways.

#1) Using JavaDoc Command Via Command Line

The command-line tool allows us to run the command through it.

This command can be executed on a command line and has the following syntax.

user@sth:~$javadoc –d doc src*

In the above command, we assume that all the files and Java classes are in the src folder. Also, the documentation will be generated in the specified ‘doc’ directory.

Note that running the “javadoc” command without any parameters or flags results in an error.

#2) Using The Tool From Any Of The Java IDEs.

All the major Java IDEs provide built-in functionality of generating documentation using the JavaDoc tool.

Using this built-in functionality is easier and also recommended than using a command-line tool to generate Java documentation.

Using JavaDoc With IntelliJIdea

Let’s generate documentation for a simple program using IntelliJIdea IDE.

We will consider the following program for which we have provided doc comments.

/** * Main class * * Please see the {@link www.softwaretestinghelp.com} class for true identity * @author SoftwareTestingHelp * */ public class Main{ /** *

main method description … * JavaDoc! *

* @param args() string array * @return void * @see JavaDoc * */ public static void main(String args()) { System.out.println('Hello,World!!'); } }

JavaDoc'u oluşturmak için programı veya projeyi derlememize gerek olmadığını biliyoruz. IntelliJIdea Ide, belgeleri oluşturmak için yerleşik bir araç sağlar. IntelliJIdea kullanarak belgeleri oluşturmak için aşağıdaki adımları izleyin.

  • Araçlar -> JavaDoc Oluştur'u tıklayın

JavaDoc oluştur

  • JavaDoc aracına tıklandığında aşağıdaki ekran açılır.

JavaDoc aracı açıldı

Burada tüm proje için mi yoksa sadece bir sınıf için mi dokümantasyon oluşturmak istediğimizi belirtebiliriz. Dokümantasyon dosyalarının oluşturulacağı çıktı dizinini de belirtebiliriz. Yukarıdaki şekilde gösterildiği gibi çeşitli başka özellikler vardır.

Tüm parametreler belirlendikten sonra Tamam'a tıklayın.

  • Artık Java Doc oluşturma sürecini çıktı penceresinde görebiliriz. Örnek bir Java Doc çıktı penceresi aşağıda gösterildiği gibidir:

JavaDoc çıktı penceresi

  • Oluşturma tamamlandığında aşağıdaki dosyalar oluşturulur.

JavaDoc üretimi

  • Main sınıfını belirttiğimiz gibi, Main.html dosyası oluşturulur. İndex.html dosyasının Main.html ile aynı içeriğe sahip olduğuna dikkat edin.
  • Help-doc.html dosyası, Java varlıklarının genel tanımlarını içerir. Bu dosyanın içeriğinin bir örneği aşağıda gösterilmiştir.

Düzenlenen API Belgeleri

  • Benzer şekilde, aşağıda Main.html dosyasındaki örnek bir içerik verilmiştir.

Main.html dosyasında örnek bir içerik

Dolayısıyla, IntelliJ fikrindeki bu aracı kullanarak dokümantasyon oluşturmanın yolu budur. Eclipse ve / veya NetBeans gibi diğer Java IDE'lerinde benzer adımları takip edebiliriz.

Sıkça Sorulan Sorular

S # 1) JavaDoc'un kullanımı nedir?

Cevap: JavaDoc aracı, JDK ile birlikte gelir. Java kaynak kodu için kod belgelerini HTML biçiminde oluşturmak için kullanılır. Bu araç, kaynak koddaki yorumların /**….*/ olarak önceden tanımlanmış bir biçimde sağlanmasını gerektirir. Bunlara belge yorumları da denir.

S # 2) Java dokümantasyon örneği nedir?

Cevap: Java Doc dokümantasyon aracı, dokümantasyonu web tarayıcısından görüntüleyebilmemiz için HTML dosyaları oluşturur. JavaDoc belgelerinin gerçek canlı örneği, Oracle Corporation'daki Java kitaplıkları için belgelerdir, http://download.oracle.com/javase/6/ dokümanlar /ateş/.

S # 3) Özel yöntemler JavaDoc'a ihtiyaç duyar mı?

Cevap: Hayır. Özel Alanlar ve yöntemler yalnızca geliştiriciler içindir. Son kullanıcı tarafından erişilemeyen özel yöntemler veya alanlar için belge sağlamanın mantığı yoktur. Java Doc ayrıca özel varlıklar için belge oluşturmaz.

Java'da liste nasıl yapılır

S # 4) JavaDoc Komutu nedir?

Cevap: Bu komut, Java kaynak dosyalarındaki bildirimleri ve belge yorumlarını ayrıştırır ve genel ve korumalı sınıflar, yuvalanmış sınıflar, oluşturucular, yöntemler, alanlar ve arabirimler için belgeleri içeren ilgili HTML belge sayfalarını oluşturur.

Ancak JavaDoc, özel varlıklar ve anonim iç sınıflar için belge oluşturmaz.

Sonuç

Bu eğitici, Java kaynak kodu için kod belgelerini HTML biçiminde oluşturmak için yararlı olan JDK ile paketlenmiş JavaDoc aracını açıkladı. Java Doc komutunu komut aracıyla çalıştırarak veya Java IDE'lerin çoğunda bulunan yerleşik JavaDoc işlevini kullanarak belgeler oluşturabiliriz.

Belgeleri oluşturmak için aracı IntelliJIdea Java IDE ile nasıl kullanabileceğimizi gördük. Öğretici ayrıca, aracın kaynak kodla ilgili tüm bilgileri detaylandıran kullanıcı dostu belgeler oluşturabilmesi için belge yorumlarıyla kullanılabilecek çeşitli etiketleri de açıkladı.

=> Java'yı Sıfırdan Öğrenmek İçin Burayı Ziyaret Edin.

Önerilen Kaynaklar

^