Terjemahan: Menggunakan sintaks Markdown di komentar Javadoc

Menggunakan Sintaks Penurunan Harga di Komentar Javadoc

Dalam postingan ini, kita akan melihat bagaimana Anda dapat menulis komentar Javadoc menggunakan Markdown alih-alih sintaksis Javadoc standar. Jadi apa itu penurunan harga? Penurunan harga adalah bahasa markup sederhana yang secara opsional dapat diterjemahkan ke dalam HTML menggunakan alat dengan nama yang sama. Penurunan harga banyak digunakan untuk memformat file readme, saat menulis postingan forum, dan dalam editor teks untuk membuat dokumen teks yang indah dengan cepat. (Wikipedia: Markdown ) Teks yang diformat dalam Markdown sangat mudah dibaca. Berbagai jenis Markdown digunakan di Stack Overflow atau GitHub untuk memformat konten buatan pengguna.

Instalasi

Secara default, alat Javadoc menggunakan komentar Javadoc untuk menghasilkan dokumentasi API sebagai HTML. Proses ini dapat dikonfigurasi ulang menggunakan Doclets . Doclet adalah program Java yang menentukan konten dan format file keluaran alat Javadoc. Markdown-doclet menggantikan Java Doclet standar dan dengan demikian memberikan pengembang kemampuan untuk menggunakan sintaks Markdown dalam komentar Javadoc mereka. Anda dapat menginstalnya di Maven menggunakan maven-javadoc-plugin. maven-javadoc-plugin 2.9 ch.raffael.doclets.pegdown.PegdownDoclet ch.raffael.pegdown-doclet pegdown-doclet 1.1 true

Menulis komentar di Markdown

Anda sekarang dapat menggunakan sintaks Markdown untuk menulis komentar Javadoc: /** * ## Large headline * ### Smaller headline * * This is a comment that contains `code` parts. * * Code blocks: * * ```java * int foo = 42; * System.out.println(foo); * ``` * * Quote blocks: * * > This is a block quote * * lists: * * - first item * - second item * - third item * * This is a text that contains an [external link][link]. * * [link]: http://external-link.com/ * * @param id the user id * @return the user object with the passed `id` or `null` if no user with this `id` is found */ public User findUser(long id) { ... } Setelah eksekusi

mvn javadoc: Javadoc

dokumen HTML API yang dihasilkan terletak di

target/situs/apidocs.

Dokumen yang dihasilkan untuk kode di atas terlihat seperti ini: Seperti yang Anda lihat dari gambar, komentar Javadoc dikonversi dengan sempurna ke HTML.

Kesimpulan

Penurunan harga memiliki keunggulan yang jelas dibandingkan sintaksis Javadoc standar: lebih mudah dibaca dalam kode sumber. Lihat saja beberapa komentar metode di java.util.Map: banyak di antaranya yang penuh dengan tag pemformatan dan sulit dibaca tanpa menggunakan alat tambahan. Namun perlu Anda ingat bahwa Markdown dapat menyebabkan masalah pada alat dan IDE yang hanya dapat bekerja dengan sintaksis Javadoc standar. Sumber: Menggunakan sintaksis Markdown dalam komentar Javadoc dari mitra JCG kami Michael Scharhag dari blog mscharhag, Pemrograman dan Barang.