Java - Komentar Dokumentasi

Bahasa Java mendukung tiga jenis komentar −

No.Pr.	Komentar &Deskripsi
1	/* teks */ Kompiler mengabaikan semuanya mulai dari /* hingga */.
2	//teks Kompilator mengabaikan semuanya mulai dari // hingga akhir baris.
3	/** dokumentasi */ Ini adalah komentar dokumentasi dan secara umum disebut komentar dokumen . Javadoc JDK alat menggunakan komentar dokumen saat menyiapkan dokumentasi yang dibuat secara otomatis.

Bab ini adalah tentang menjelaskan Javadoc. Kita akan melihat bagaimana kita dapat menggunakan Javadoc untuk menghasilkan dokumentasi yang berguna untuk kode Java.

Apa itu Javadoc?

Javadoc adalah alat yang disertakan dengan JDK dan digunakan untuk menghasilkan dokumentasi kode Java dalam format HTML dari kode sumber Java, yang memerlukan dokumentasi dalam format yang telah ditentukan sebelumnya.

Berikut adalah contoh sederhana di mana baris di dalam /*….*/ adalah komentar multi-baris Java. Demikian pula, baris yang mendahului // adalah komentar satu baris Java.

Contoh

/**
* 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!");
   }
}

Anda dapat menyertakan tag HTML yang diperlukan di dalam bagian deskripsi. Misalnya, contoh berikut menggunakan

....

untuk heading dan

telah digunakan untuk membuat paragraf break −

Contoh

/**
* <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!");
   }
}

Tag javadoc

Alat javadoc mengenali tag berikut −

Tag	Deskripsi	Sintaks
@penulis	Menambahkan penulis kelas.	@nama-teks penulis
{@code}	Menampilkan teks dalam font kode tanpa menafsirkan teks sebagai markup HTML atau tag javadoc bersarang.
	Mewakili jalur relatif ke direktori akar dokumen yang dihasilkan dari halaman mana pun yang dihasilkan.
@tidak digunakan lagi	Menambahkan komentar yang menunjukkan bahwa API ini tidak boleh digunakan lagi.	@teks usang yang tidak digunakan lagi
@exception	Menambahkan Melempar subjudul ke dokumentasi yang dihasilkan, dengan nama kelas dan teks deskripsi.	@pengecualian deskripsi nama kelas
	Mewarisi komentar dari terdekat kelas yang dapat diwarisi atau antarmuka yang dapat diimplementasikan.	Mewarisi komentar dari kelas super langsung.
	Menyisipkan tautan sebaris dengan label teks yang terlihat yang menunjuk ke dokumentasi untuk paket, kelas, atau nama anggota yang ditentukan dari kelas yang direferensikan.	{@link package.class#member label}
	Identik dengan {@link}, kecuali label tautan ditampilkan dalam teks biasa daripada font kode.	{@linkplain package.class#member label}
@param	Menambahkan parameter dengan nama parameter yang ditentukan diikuti dengan deskripsi yang ditentukan ke bagian "Parameter".	@param deskripsi nama parameter
@return	Menambahkan bagian "Pengembalian" dengan teks deskripsi.	@deskripsi pengembalian
@lihat	Menambahkan judul "Lihat Juga" dengan tautan atau entri teks yang mengarah ke referensi.	@lihat referensi
@serial	Digunakan dalam komentar dokumen untuk bidang default yang dapat diserialisasi.	@deskripsi bidang @serial | termasuk | kecualikan
@serialData	Mendokumentasikan data yang ditulis oleh metode writeObject() atau writeExternal().	@serialData data-description
@serialField	Mendokumentasikan komponen ObjectStreamField.	@serialField bidang-nama bidang-jenis-bidang-deskripsi
@sejak	Menambahkan judul "Sejak" dengan teks-sejak yang ditentukan ke dokumentasi yang dihasilkan.	@sejak rilis
@melempar	Tag @throws dan @exception adalah sinonim.	@melempar deskripsi nama kelas
	Bila {@value} digunakan dalam komentar dokumen bidang statis, ini akan menampilkan nilai konstanta tersebut.	{@value package.class#field}
@versi	Menambahkan subjudul "Versi" dengan teks versi yang ditentukan ke dokumen yang dihasilkan saat opsi -versi digunakan.	@versi versi-teks

Contoh

Program berikut menggunakan beberapa tag penting yang tersedia untuk komentar dokumentasi. Anda dapat menggunakan tag lain berdasarkan kebutuhan Anda.

Dokumentasi tentang kelas AddNum akan dibuat dalam file HTML AddNum.html tetapi pada saat yang sama file master dengan nama index.html juga akan dibuat.

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);
   }
}

Sekarang, proses file AddNum.java di atas menggunakan utilitas javadoc sebagai berikut

$ 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
$

Anda dapat memeriksa semua dokumentasi yang dihasilkan di sini AddNum. Jika Anda menggunakan JDK 1.7 maka javadoc tidak menghasilkan stylesheet.css yang bagus , jadi kami sarankan untuk mengunduh dan menggunakan stylesheet standar dari https://docs.Oracle.com/javase/7/docs/api/stylesheet.css