Pengenalan kepada Javadoc

1. Gambaran keseluruhan

Dokumentasi API yang baik adalah salah satu daripada banyak faktor yang menyumbang kepada kejayaan keseluruhan projek perisian.

Nasib baik, semua versi moden JDK menyediakan alat Javadoc - untuk menghasilkan dokumentasi API dari komen yang terdapat dalam kod sumber.

Prasyarat:

1. JDK 1.4 (JDK 7+ disyorkan untuk versi terbaru plugin Maven Javadoc)
2. Folder JDK / bin ditambahkan ke pemboleh ubah persekitaran PATH
3. (Pilihan) IDE dengan alat terbina dalam

2. Komen Javadoc

Mari mulakan dengan komen.

Struktur komen Javadoc kelihatan sangat mirip dengan komen berbilang baris biasa , tetapi perbezaan utama adalah tanda bintang tambahan pada awalnya:

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

Komen gaya Javadoc mungkin juga mengandungi tag HTML.

2.1. Format Javadoc

Komen Javadoc boleh diletakkan di atas mana-mana kelas, kaedah, atau bidang yang ingin didokumentasikan.

Komen ini biasanya terdiri daripada dua bahagian:

1. Penerangan mengenai apa yang kami komen
2. Tag blok mandiri (ditandai dengan simbol " @ ") yang menerangkan meta-data tertentu

Kami akan menggunakan beberapa tag blok yang lebih biasa dalam contoh kami. Untuk senarai lengkap tag blok, lawati panduan rujukan.

2.2. Javadoc di Peringkat Kelas

Mari lihat bagaimana komen Javadoc peringkat 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 mempunyai penerangan ringkas dan dua teg blok yang berbeza - mandiri dan sebaris:

• Tag mandiri muncul selepas keterangan dengan tag sebagai kata pertama dalam satu baris, misalnya, tag @author
• Tag sebaris boleh muncul di mana sahaja dan dikelilingi dengan tanda kurung keriting , misalnya, tag @link dalam keterangan

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

• {@link} menyediakan pautan sebaris ke bahagian rujukan kod sumber kami
• @autautkan nama pengarang yang menambahkan kelas, kaedah, atau bidang yang dikomentari

2.3. Javadoc di Peringkat Lapangan

Kami juga boleh menggunakan penerangan tanpa tanda blok seperti ini di dalam kelas SuperHero kami :

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

Medan peribadi tidak akan menghasilkan Javadoc untuknya melainkan jika kita secara jelas memberikan pilihan -private ke perintah Javadoc.

2.4. Javadoc pada Tahap Kaedah

Kaedah boleh mengandungi pelbagai tag blok Javadoc.

Mari kita lihat kaedah yang kita 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 Cara mengandungi kedua-dua penerangan dan banyak tag blok yang berdiri sendiri.

Terdapat banyak tanda blok untuk membantu menghasilkan dokumentasi yang betul dan kami dapat memasukkan pelbagai jenis maklumat. Kita juga boleh menggunakan tag HTML asas dalam komen.

Mari kita lihat tag yang kita temui dalam contoh di atas:

• @param memberikan penerangan berguna mengenai parameter atau input kaedah yang semestinya diharapkan
• @return memberikan penerangan mengenai kaedah yang akan atau boleh dikembalikan oleh kaedah
• @see akan menghasilkan pautan yang serupa dengan tag {@link} , tetapi lebih dalam konteks rujukan dan tidak sebaris
• @since menentukan versi kelas, bidang, atau kaedah yang ditambahkan ke projek
• @version menentukan versi perisian, yang biasa digunakan dengan makro% I% dan% G%
• @throws digunakan untuk menjelaskan lebih lanjut mengenai kes yang diharapkan oleh perisian untuk pengecualian
• @deprecated memberikan penjelasan mengapa kod tidak digunakan lagi, kapan ia mungkin tidak digunakan lagi, dan apa alternatifnya

Walaupun kedua-dua bahagian itu secara teknikal pilihan, kami memerlukan sekurang-kurangnya satu alat Javadoc untuk menghasilkan sesuatu yang bermakna.

3. Penjanaan Javadoc

Untuk menghasilkan halaman Javadoc kami, kami ingin melihat alat baris perintah yang dihantar dengan JDK, dan plugin Maven.

3.1. Alat Baris Perintah Javadoc

Alat baris arahan Javadoc sangat kuat tetapi mempunyai beberapa kerumitan yang melekat padanya.

Menjalankan perintah javadoc tanpa pilihan atau parameter akan menghasilkan ralat dan parameter output yang diharapkannya.

Kita sekurang-kurangnya perlu menentukan pakej atau kelas yang kita mahu dokumentasi dihasilkan.

Mari buka baris arahan dan arahkan ke direktori projek.

Dengan anggapan kelas semuanya ada di folder src di direktori projek:

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

Ini akan menghasilkan dokumentasi dalam direktori yang disebut doc seperti yang ditentukan dengan bendera - d . Sekiranya terdapat banyak pakej atau fail, kami perlu memberikan semuanya.

Menggunakan IDE dengan fungsi bawaan tentu saja lebih mudah dan disyorkan secara umum.

3.2. Javadoc With Maven Plugin

Kami juga boleh menggunakan plugin Maven Javadoc:

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

Di direktori asas projek, kami menjalankan perintah untuk menghasilkan Javadocs kami ke direktori di target \ site:

[email protected]:~$ mvn javadoc:javadoc

Plugin Maven sangat kuat dan memudahkan pembuatan dokumen yang kompleks dengan lancar.

Mari kita lihat bagaimana rupa halaman Javadoc yang dihasilkan:

Kami dapat melihat pemandangan pokok kelas SuperHero kami yang dilanjutkan. Kami dapat melihat penerangan, bidang, dan kaedah kami, dan kami dapat mengklik pautan untuk maklumat lebih lanjut.

Pandangan terperinci kaedah kami kelihatan seperti ini:

3.3. Tag Javadoc Tersuai

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

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 pantas ini merangkumi cara menulis Javadocs asas dan menghasilkannya dengan baris arahan Javadoc.

Cara yang lebih mudah untuk menghasilkan dokumentasi adalah menggunakan pilihan IDE terbina dalam atau memasukkan plugin Maven ke dalam fail pom.xml kami dan menjalankan perintah yang sesuai.

Contoh kod, seperti biasa, terdapat di GitHub.