Komentar Dokumentasi Java: Menguasai Javadoc dan Jenis Komentar
Bahasa Java mendukung tiga jenis komentar −
| Sr.No. | Komentar & Deskripsi |
| 1 | /* text */ Compiler mengabaikan semua dari /* hingga */. |
| 2 | //text Compiler mengabaikan semua dari // hingga akhir baris. |
| 3 | /** documentation */ Ini adalah komentar dokumentasi dan secara umum disebut doc comment. Alat JDK javadoc menggunakan doc comments saat menyusun dokumentasi yang dihasilkan secara otomatis. |
Bab ini sepenuhnya 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 datang dengan JDK dan digunakan untuk menghasilkan dokumentasi kode Java dalam format HTML dari kode sumber Java, yang memerlukan dokumentasi dalam format yang telah ditentukan.
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 <h1>....</h1> untuk judul dan <p> telah digunakan untuk membuat paragraf −
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-tag berikut −
| Tag | Deskripsi | Sintaks |
| @author | Menambahkan penulis kelas. | @author name-text |
| {@code} | Menampilkan teks dalam font kode tanpa menafsirkan teks sebagai markup HTML atau tag javadoc bersarang. | {@code text} |
| {@docRoot} | Mewakili jalur relatif ke direktori root dokumen yang dihasilkan dari halaman yang dihasilkan. | {@docRoot} |
| @deprecated | Menambahkan komentar yang menunjukkan bahwa API ini tidak boleh lagi digunakan. | @deprecated deprecatedtext |
| @exception | Menambahkan subjudul Throws ke dokumentasi yang dihasilkan, dengan nama kelas dan teks deskripsi. | @exception class-name description |
| {@inheritDoc} | Mewarisi komentar dari kelas atau antarmuka yang dapat diwarisi terdekat. | Mewarisi komentar dari superclass segera di atas. |
| {@link} | Menyisipkan tautan inline dengan label teks yang terlihat yang menunjuk ke dokumentasi untuk nama paket, kelas, atau anggota dari kelas yang dirujuk yang ditentukan. | {@link package.class#member label} |
| {@linkplain} | 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 parameter-name description |
| @return | Menambahkan bagian "Returns" dengan teks deskripsi. | @return description |
| @see | Menambahkan judul "See Also" dengan tautan atau entri teks yang menunjuk ke referensi. | @see reference |
| @serial | Digunakan dalam doc comment untuk kolom serializable default. | @serial field-description | include | exclude |
| @serialData | Mendokumentasikan data yang ditulis oleh metode writeObject( ) atau writeExternal( ). | @serialData data-description |
| @serialField | Mendokumentasikan komponen ObjectStreamField. | @serialField field-name field-type field-description |
| @since | Menambahkan judul "Since" dengan since-text yang ditentukan ke dokumentasi yang dihasilkan. | @since release |
| @throws | Tag @throws dan @exception adalah sinonim. | @throws class-name description |
| {@value} | Saat {@value} digunakan dalam doc comment dari kolom statis, itu menampilkan nilai konstanta tersebut. | {@value package.class#field} |
| @version | Menambahkan subjudul "Version" dengan version-text yang ditentukan ke dokumen yang dihasilkan saat opsi -version digunakan. | @version version-text |
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 dihasilkan 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 menyarankan untuk mengunduh dan menggunakan stylesheet standar dari https://docs.oracle.com/javase/7/docs/api/stylesheet.css
