Dokumentasikan Kode Java Anda Secara Otomatis Dengan Javadoc

Jika Anda melakukan pemrograman apa pun, Anda akan menyadari bahwa salah satu tugas paling membosankan yang terlibat adalah mendokumentasikan kode Anda. Apakah Anda merasa agak mengganggu atau tugas yang Anda hadapi dengan ketakutan mutlak, dokumentasi kode sangat penting. Orang lain perlu memahami cara kerja kode Anda, dan Anda bahkan mungkin salah satunya jika Anda membacanya di kemudian hari!

Java dengan mudah menyediakan solusi bawaan untuk masalah tersebut: Javadoc.

Javadoc Dapat Membantu Anda Mendokumentasikan Kode Anda Secara Otomatis

Semoga sudah follow praktik pengkodean yang baik dan sertakan komentar penjelasan dalam kode Anda. Meskipun jenis komentar dalam kode ini tentu saja membantu, itu tidak benar-benar memberikan apa pun yang sebanding dengan manual.

Tentu, programmer lain dapat melihat kode Anda dan membaca tentang kelas, metode, dan fungsi tertentu yang ada di depannya. Namun, sangat sulit untuk mendapatkan gambaran umum yang baik tentang semua kode atau menemukan fungsi yang dapat berguna ketika Anda tidak mengetahuinya. Javadoc bertujuan untuk memecahkan masalah itu.

Javadoc akan menghasilkan manual HTML yang terperinci dan ramah pembaca untuk semua kode Anda secara otomatis. Yang terbaik, ia melakukannya dengan menggunakan komentar kode yang mungkin sudah Anda tulis.

Apa Tepatnya Javadoc dan Bagaimana Cara Kerjanya?

Javadoc adalah program mandiri yang dibundel dengan rilis Java development kit (JDK) Oracle. Bahkan, Anda tidak dapat mengunduhnya secara terpisah. Saat Anda mengunduh dan instal salah satu versi JDK Oracle, itu juga akan menginstal Javadoc.

Saat Anda menjalankannya, Javadoc menghasilkan dokumentasi HTML dari komentar yang diformat khusus dalam kode sumber Java Anda. Proses ini menciptakan dokumentasi yang lebih berguna dan mudah dibaca sekaligus mendorong praktik terbaik.

Singkatnya, Javadoc memungkinkan Anda untuk menulis kode dan dokumentasinya secara bersamaan. Ini menyederhanakan alur kerja Anda dan memungkinkan Anda menggunakan waktu dengan lebih efisien.

Javadoc bekerja dengan mem-parsing komentar yang diformat khusus dalam kode Anda dan mengubahnya menjadi output HTML. Satu-satunya perubahan yang benar-benar perlu Anda lakukan adalah memasukkan string tertentu dalam komentar Anda. Ini membuat Javadoc tahu apa yang ingin Anda sertakan dalam dokumentasi akhir.

Komentar Javadoc harus segera mendahului deklarasi kelas, bidang, konstruktor, atau metode. Komentar itu sendiri harus:

• Mulailah dengan tiga karakter /**.
• Sertakan tanda bintang di awal setiap baris baru.
• Dekat dengan dua karakter */.

Di dalam komentar, Anda dapat memasukkan HTML dalam hasil akhir dan menyertakan tag yang akan menghasilkan tautan ke bagian yang relevan dari basis kode Anda. Anda bahkan dapat menggunakan hal-hal seperti tag gambar HTML untuk menyertakan gambar dalam dokumentasi akhir. Setelah Anda terbiasa dengan format dan tag yang tersedia, menulis komentar seperti itu sangat mudah.

Berikut adalah contoh untuk mengilustrasikan komentar Javadoc sederhana yang menjelaskan fungsi yang mendapatkan gambar dari URL dan mencetaknya ke layar. Komentar segera mendahului fungsi dan menjelaskan apa yang dilakukannya. Blok komentar ini juga menggunakan tiga tag khusus bagian: @param, @kembali, dan @melihat.

/**
* Mengembalikan objek Gambar yang kemudian dapat dilukis di layar.
* Argumen url harus menentukan absolut {@tautan URL}. Nama
* argumen adalah penentu yang relatif terhadap argumen url.
* 

* Metode ini selalu kembali dengan segera, terlepas dari apakah
* gambar ada. Kapan ini applet mencoba menggambar gambar pada
* layar, data akan dimuat. Grafis primitif
* yang menggambar gambar akan melukis secara bertahap di layar.
*
* @param url URL absolut yang memberikan lokasi dasar gambar
* @param beri nama lokasi gambar, relatif terhadap argumen url
* @kembali gambar di URL yang ditentukan
* @melihat Gambar
*/
publik Gambar dapatkan gambar(URL URL, Nama string){
mencoba {
kembali dapatkanGambar(baru URL(url, nama));
 } menangkap (MalformedURLException e) {
kembalibatal;
 }
}

Ketika Javadoc memproses kode di atas, itu menghasilkan halaman web yang mirip dengan berikut:

Peramban merender keluaran Javadoc dengan cara yang sama seperti ia menampilkan dokumen HTML apa pun. Javadoc mengabaikan spasi ekstra dan jeda baris kecuali Anda menggunakan tag HTML untuk membuat spasi itu.

@tag yang digunakan di akhir komentar menghasilkan Parameter, Kembali, dan Lihat juga bagian yang Anda lihat.

Anda harus mengikuti @param tag dengan nama parameter, spasi, dan deskripsinya. Dalam kasus di atas, ada dua parameter: url dan nama. Perhatikan bahwa keduanya muncul di bawah judul Parameter yang sama di output dokumentasi. Anda dapat membuat daftar parameter sebanyak yang diperlukan untuk fungsi atau metode yang Anda gambarkan.

Itu @kembali tag mendokumentasikan nilai yang dikembalikan oleh fungsi, jika ada. Ini bisa berupa deskripsi satu kata sederhana atau banyak kalimat, tergantung pada situasinya.

Itu @melihat tag memungkinkan Anda untuk menandai fungsi lain yang terkait atau relevan. Dalam hal ini, tag @see merujuk ke fungsi lain yang disebut hanya Gambar. Perhatikan bahwa referensi yang dibuat dengan tag ini adalah tautan yang dapat diklik, memungkinkan pembaca untuk melompat ke item yang dirujuk di HTML akhir.

Ada lebih banyak tag yang tersedia seperti @version, @author, @exception, dan lainnya. Bila digunakan dengan benar, tag membantu menghubungkan item satu sama lain dan memungkinkan untuk menavigasi dokumentasi dengan mudah.

Menjalankan Javadoc pada Kode Sumber Anda

Anda memanggil Javadoc pada baris perintah. Anda dapat menjalankannya pada satu file, seluruh direktori, paket java, atau di seluruh daftar file individual. Secara default, Javadoc akan menghasilkan file dokumentasi HTML di direktori tempat Anda memasukkan perintah. Untuk mendapatkan bantuan tentang perintah khusus yang tersedia, cukup masukkan:

javadoc --Tolong

Untuk melihat dengan tepat apa yang dapat dilakukan Javadoc secara lebih rinci, lihat dokumentasi resmi dari Peramal. Untuk membuat kumpulan dokumentasi cepat pada satu file atau direktori, Anda dapat memasukkan javadoc pada baris perintah diikuti dengan nama file atau wildcard.

javadoc ~/code/nama file.java
javadoc ~/code/*.Jawa

Di atas adalah daftar file dan direktori yang telah dibuat Javadoc. Seperti yang Anda lihat, ada beberapa dari mereka. Untuk alasan ini, Anda harus yakin bahwa Anda tidak berada di direktori yang sama dengan kode sumber Anda saat menjalankan program. Melakukan hal itu bisa membuat cukup berantakan.

Untuk melihat dokumen yang baru Anda buat, cukup buka index.html file di browser pilihan Anda. Anda akan mendapatkan halaman seperti berikut:

Ini adalah dokumentasi untuk satu kelas Java pendek untuk mendemonstrasikan hasilnya. Header menunjukkan nama kelas serta metode yang disertakan di dalamnya. Menggulir ke bawah mengungkapkan definisi yang lebih rinci dari masing-masing metode kelas.

Seperti yang Anda lihat, untuk semua jenis proyek Java, terutama yang besar dengan ribuan baris kode, jenis dokumentasi ini sangat berharga. Akan menjadi tantangan untuk mempelajari tentang basis kode yang besar dengan membaca kode sumbernya. Halaman Javadoc membuat proses ini lebih cepat dan lebih mudah diikuti.

Javadoc dapat membantu Anda menjaga kode Java dan semua dokumentasi yang relevan terorganisir dan mudah digunakan. Apakah Anda melakukannya untuk diri Anda sendiri di masa depan yang pelupa atau untuk membuat segalanya lebih mudah bagi tim besar, Javadoc adalah alat yang ampuh yang dapat mengubah cara Anda menulis dan berinteraksi dengan pengkodean Java Anda proyek.

8 Blog Java Terbaik untuk Programmer

Baca Selanjutnya