Java - Dokümantasyon Yorumları

Java dili üç tür yorumu destekler -

Sr.No.	Yorum ve Açıklama
1	*/ text /* Derleyici / * ile * / arasındaki her şeyi yok sayar.
2	//text Derleyici // satırın sonuna kadar her şeyi yok sayar.
3	/ documentation /* Bu bir dokümantasyon açıklamasıdır ve genel olarak doc comment. JDK javadocaracı, otomatik olarak oluşturulan belgeleri hazırlarken belge açıklamalarını kullanır .

Bu bölüm tamamen Javadoc'u açıklamakla ilgili. Java kodu için yararlı dokümantasyon oluşturmak için Javadoc'u nasıl kullanabileceğimizi göreceğiz.

Javadoc nedir?

Javadoc, JDK ile birlikte gelen bir araçtır ve önceden tanımlanmış bir formatta dokümantasyon gerektiren Java kaynak kodundan HTML formatında Java kodu dokümantasyonu oluşturmak için kullanılır.

Aşağıda /*….*/ içindeki satırların Java çok satırlı yorumları olduğu basit bir örnek verilmiştir. Benzer şekilde, önceki satır Java tek satırlı yorumdur.

Misal

/**
* The HelloWorld program implements an application that
* simply displays "Hello World!" to the standard output.
*
* @author  Zara Ali
* @version 1.0
* @since   2014-03-31 
*/
public class HelloWorld {

   public static void main(String[] args) {
      // Prints Hello, World! on standard output.
      System.out.println("Hello World!");
   }
}

Açıklama kısmına gerekli HTML etiketlerini ekleyebilirsiniz. Örneğin, aşağıdaki örnekte başlık için <h1> .... </h1> ve paragraf sonu oluşturmak için <p> kullanılmıştır -

Misal

/**
* <h1>Hello, World!</h1>
* The HelloWorld program implements an application that
* simply displays "Hello World!" to the standard output.
* <p>
* Giving proper comments in your program makes it more
* user friendly and it is assumed as a high quality code.
* 
*
* @author  Zara Ali
* @version 1.0
* @since   2014-03-31 
*/
public class HelloWorld {

   public static void main(String[] args) {
      // Prints Hello, World! on standard output.
      System.out.println("Hello World!");
   }
}

Javadoc Etiketleri

Javadoc aracı aşağıdaki etiketleri tanır -

Etiket	Açıklama	Sözdizimi
@yazar	Bir sınıfın yazarını ekler.	@author adı-metin
{@code}	Metni HTML biçimlendirmesi veya yuvalanmış javadoc etiketleri olarak yorumlamadan, metni kod yazı tipinde görüntüler.	{@code text}
{@docRoot}	Oluşturulan herhangi bir sayfadan oluşturulan belgenin kök dizininin göreli yolunu temsil eder.	{@docRoot}
@deprecated	Bu API'nin artık kullanılmaması gerektiğini belirten bir yorum ekler.	@deprecated kullanımdan kaldırılmış metin
@istisna	Bir ekler Throws sınıf adı ve açıklama metni ile oluşturulan dokümantasyonun alt başlığı.	@exception sınıf adı açıklaması
{@inheritDoc}	Şuradan bir yorum devralır: nearest devralınabilir sınıf veya uygulanabilir arayüz.	En yakın üst sınıftan bir yorum alır.
{@link}	Başvurulan bir sınıfın belirtilen paket, sınıf veya üye adı için belgelere işaret eden görünür metin etiketli bir satır içi bağlantı ekler.	{@link package.class # üye etiketi}
{@linkplain}	Bağlantının etiketinin kod yazı tipinden çok düz metin olarak görüntülenmesi dışında, {@link} ile aynıdır.	{@linkplain package.class # üye etiketi}
@param	Belirtilen parametre adı ve ardından belirtilen açıklamayı "Parametreler" bölümüne içeren bir parametre ekler.	@param parametre adı açıklaması
@dönüş	Açıklama metniyle bir "İadeler" bölümü ekler.	@return açıklaması
@görmek	Referansa işaret eden bir bağlantı veya metin girişi içeren bir "Ayrıca Bkz." Başlığı ekler.	@ bkz. referans
@seri	Varsayılan serileştirilebilir alan için belge yorumunda kullanılır.	@ seri alan açıklaması \| dahil \| hariç tutmak
@serialData	WriteObject () veya writeExternal () yöntemleriyle yazılan verileri belgeler.	@serialData veri açıklaması
@serialField	Bir ObjectStreamField bileşenini belgeler.	@serialField alan-adı alan-türü alan-açıklaması
@dan beri	Oluşturulan belgelere belirtilen başlangıç metni ile bir "Başlangıç" başlığı ekler.	@since release
@throws	@Throws ve @exception etiketleri eşanlamlıdır.	@ sınıf adı açıklamasını atar
{@value}	Statik bir alanın belge yorumunda {@value} kullanıldığında, bu sabitin değerini görüntüler.	{@value package.class # alanı}
@version	-Version seçeneği kullanıldığında, oluşturulan dokümanlara belirtilen sürüm metni ile bir "Sürüm" alt başlığı ekler.	@version sürüm metni

Misal

Aşağıdaki program, dokümantasyon yorumları için mevcut olan birkaç önemli etiketi kullanır. Gereksinimlerinize göre diğer etiketleri kullanabilirsiniz.

AddNum sınıfıyla ilgili belgeler, AddNum.html HTML dosyasında üretilecek, ancak aynı zamanda index.html adlı bir ana dosya da oluşturulacaktır.

import java.io.*;

/**
* <h1>Add Two Numbers!</h1>
* The AddNum program implements an application that
* simply adds two given integer numbers and Prints
* the output on the screen.
* <p>
* <b>Note:</b> Giving proper comments in your program makes it more
* user friendly and it is assumed as a high quality code.
*
* @author  Zara Ali
* @version 1.0
* @since   2014-03-31
*/
public class AddNum {
   /**
   * This method is used to add two integers. This is
   * a the simplest form of a class method, just to
   * show the usage of various javadoc Tags.
   * @param numA This is the first paramter to addNum method
   * @param numB  This is the second parameter to addNum method
   * @return int This returns sum of numA and numB.
   */
   public int addNum(int numA, int numB) {
      return numA + numB;
   }

   /**
   * This is the main method which makes use of addNum method.
   * @param args Unused.
   * @return Nothing.
   * @exception IOException On input error.
   * @see IOException
   */

   public static void main(String args[]) throws IOException {
      AddNum obj = new AddNum();
      int sum = obj.addNum(10, 20);

      System.out.println("Sum of 10 and 20 is :" + sum);
   }
}

Şimdi, yukarıdaki AddNum.java dosyasını javadoc yardımcı programını kullanarak aşağıdaki gibi işleyin -

$ javadoc AddNum.java
Loading source file AddNum.java...
Constructing Javadoc information...
Standard Doclet version 1.7.0_51
Building tree for all the packages and classes...
Generating /AddNum.html...
AddNum.java:36: warning - @return tag cannot be used in method with void return type.
Generating /package-frame.html...
Generating /package-summary.html...
Generating /package-tree.html...
Generating /constant-values.html...
Building index for all the packages and classes...
Generating /overview-tree.html...
Generating /index-all.html...
Generating /deprecated-list.html...
Building index for all classes...
Generating /allclasses-frame.html...
Generating /allclasses-noframe.html...
Generating /index.html...
Generating /help-doc.html...
1 warning
$

Oluşturulan tüm belgeleri buradan kontrol edebilirsiniz - EkNum . JDK 1.7 kullanıyorsanız, javadoc harika birstylesheet.css, bu nedenle standart stil sayfasını şuradan indirmenizi ve kullanmanızı öneririz: https://docs.oracle.com/javase/7/docs/api/stylesheet.css