Pengantar Javadoc

1. Ikhtisar

Dokumentasi API yang baik adalah salah satu dari banyak faktor yang berkontribusi pada kesuksesan keseluruhan proyek perangkat lunak.

Untungnya, semua versi modern JDK menyediakan alat Javadoc - untuk membuat dokumentasi API dari komentar yang ada di kode sumber.

Prasyarat:

  1. JDK 1.4 (JDK 7+ direkomendasikan untuk versi terbaru plugin Maven Javadoc)
  2. Folder JDK / bin ditambahkan ke variabel lingkungan PATH
  3. (Opsional) IDE dengan alat bawaan

2. Komentar Javadoc

Mari kita mulai dengan komentar.

Struktur komentar Javadoc terlihat sangat mirip dengan komentar banyak baris biasa , tetapi perbedaan utamanya adalah tanda bintang ekstra di awal:

// This is a single line comment /* * This is a regular multi-line comment */ /** * This is a Javadoc */

Komentar gaya Javadoc mungkin berisi tag HTML juga.

2.1. Format Javadoc

Komentar Javadoc dapat ditempatkan di atas setiap kelas, metode, atau bidang yang ingin kita dokumentasikan.

Komentar ini biasanya terdiri dari dua bagian:

  1. Deskripsi tentang apa yang kami komentari
  2. Tag blok mandiri (ditandai dengan simbol " @ ") yang menjelaskan meta-data tertentu

Kami akan menggunakan beberapa tag blok yang lebih umum dalam contoh kami. Untuk daftar lengkap tag blok, kunjungi panduan referensi.

2.2. Javadoc di Tingkat Kelas

Mari kita lihat seperti apa komentar Javadoc tingkat kelas:

/** * Hero is the main entity we'll be using to . . . * * Please see the {@link com.baeldung.javadoc.Person} class for true identity * @author Captain America * */ public class SuperHero extends Person { // fields and methods }

Kami memiliki deskripsi singkat dan dua tag blok yang berbeda- mandiri dan sebaris:

  • Tag mandiri muncul setelah deskripsi dengan tag sebagai kata pertama dalam baris, misalnya, tag @author
  • Tag sebaris dapat muncul di mana saja dan dikelilingi dengan tanda kurung kurawal , misalnya, tag @link dalam deskripsi

Dalam contoh kami, kami juga dapat melihat dua jenis tag blok yang digunakan:

  • {@link} memberikan tautan sebaris ke bagian referensi dari kode sumber kami
  • @author nama penulis yang menambahkan kelas, metode, atau bidang yang dikomentari

2.3. Javadoc di Tingkat Lapangan

Kami juga dapat menggunakan deskripsi tanpa tag blok seperti ini di dalam kelas SuperHero kami :

/** * The public name of a hero that is common knowledge */ private String heroName;

Bidang pribadi tidak akan dibuat Javadoc untuk mereka kecuali kita secara eksplisit meneruskan opsi -private ke perintah Javadoc.

2.4. Javadoc di Level Metode

Metode dapat berisi berbagai tag blok Javadoc.

Mari kita lihat metode yang kami gunakan:

/** * 

This is a simple description of the method. . . * Superman! *

* @param incomingDamage the amount of incoming damage * @return the amount of health hero has after attack * @see HERO-402 * @since 1.0 */ public int successfullyAttacked(int incomingDamage) { // do things return 0; }

The successfullyAttacked Metode berisi baik penjelasan dan berbagai blok mandiri tag.

Ada banyak tag blok untuk membantu menghasilkan dokumentasi yang tepat dan kami dapat menyertakan semua jenis informasi yang berbeda. Kami bahkan dapat menggunakan tag HTML dasar di komentar.

Mari kita bahas tag yang kita temukan pada contoh di atas:

  • @param memberikan deskripsi berguna apa pun tentang parameter atau masukan metode yang diharapkan
  • @return memberikan deskripsi tentang metode apa yang akan atau dapat dikembalikan
  • @see akan menghasilkan tautan yang mirip dengan tag {@link} , tetapi lebih dalam konteks referensi dan bukan sebaris
  • @since menentukan versi kelas, bidang, atau metode yang ditambahkan ke proyek
  • @version menentukan versi perangkat lunak, yang biasa digunakan dengan makro% I% dan% G%
  • @throws digunakan untuk menjelaskan lebih lanjut kasus yang mengharapkan pengecualian dari perangkat lunak
  • @deprecated memberikan penjelasan mengapa kode tidak digunakan lagi, kapan mungkin sudah tidak digunakan lagi, dan apa alternatifnya

Meskipun kedua bagian secara teknis bersifat opsional, kami memerlukan setidaknya satu agar alat Javadoc menghasilkan sesuatu yang berarti.

3. Generasi Javadoc

Untuk membuat halaman Javadoc kita, kita ingin melihat alat baris perintah yang disertakan dengan JDK, dan plugin Maven.

3.1. Alat Baris Perintah Javadoc

Alat baris perintah Javadoc sangat kuat tetapi memiliki beberapa kerumitan yang melekat padanya.

Menjalankan perintah javadoc tanpa opsi atau parameter apa pun akan menghasilkan kesalahan dan parameter keluaran yang diharapkan.

Kita harus setidaknya menentukan paket atau kelas apa yang kita inginkan untuk dibuatkan dokumentasi.

Mari buka baris perintah dan arahkan ke direktori proyek.

Dengan asumsi semua kelas ada di folder src di direktori proyek:

[email protected]:~$ javadoc -d doc src\*

Ini akan menghasilkan dokumentasi dalam direktori bernama doc seperti yang ditentukan dengan flag- d . Jika ada beberapa paket atau file, kami harus menyediakan semuanya.

Memanfaatkan IDE dengan fungsionalitas bawaan, tentu saja, lebih mudah dan umumnya direkomendasikan.

3.2. Javadoc Dengan Plugin Maven

Kami juga dapat menggunakan plugin Maven Javadoc:

   org.apache.maven.plugins maven-javadoc-plugin 3.0.0  1.8 1.8   ...    

Di direktori dasar proyek, kami menjalankan perintah untuk menghasilkan Javadocs kami ke direktori di target \ site:

[email protected]:~$ mvn javadoc:javadoc

Plugin Maven sangat kuat dan memfasilitasi pembuatan dokumen yang kompleks dengan mulus.

Sekarang mari kita lihat seperti apa halaman Javadoc yang dihasilkan:

Kita dapat melihat tampilan hierarki dari kelas yang dikembangkan oleh kelas SuperHero kita . Kami dapat melihat deskripsi, bidang, dan metode kami, dan kami dapat mengklik tautan untuk informasi lebih lanjut.

Tampilan detail dari metode kami terlihat seperti ini:

3.3. Tag Javadoc Kustom

Selain menggunakan tag blok yang telah ditentukan untuk memformat dokumentasi kami, kami juga dapat membuat tag blok kustom.

In order to do so, we just need to include a -tag option to our Javadoc command line in the format of ::.

In order to create a custom tag called @location allowed anywhere, which is displayed in the “Notable Locations” header in our generated document, we need to run:

[email protected]:~$ javadoc -tag location:a:"Notable Locations:" -d doc src\*

In order to use this tag, we can add it to the block section of a Javadoc comment:

/** * This is an example... * @location New York * @returns blah blah */

The Maven Javadoc plugin is flexible enough to also allow definitions of our custom tags in our pom.xml.

In order to set up the same tag above for our project, we can add the following to the section of our plugin:

...   location a Notable Places:   ...

This way allows us to specify the custom tag once, instead of specifying it every time.

4. Conclusion

Tutorial pengenalan singkat ini membahas cara menulis Javadoc dasar dan membuatnya dengan baris perintah Javadoc.

Cara yang lebih mudah untuk menghasilkan dokumentasi adalah dengan menggunakan opsi IDE bawaan atau menyertakan plugin Maven ke dalam file pom.xml kami dan menjalankan perintah yang sesuai.

Contoh kode, seperti biasa, dapat ditemukan di GitHub.