Terjemahan: Nggunakake sintaks Markdown ing komentar Javadoc

Nggunakake Markdown Syntax ing Komentar Javadoc

Ing kirim iki, kita bakal ndeleng carane sampeyan bisa nulis komentar Javadoc nggunakake Markdown tinimbang sintaks Javadoc standar. Dadi apa Markdown? Markdown minangka basa markup prasaja sing opsional bisa diterjemahake menyang HTML nggunakake alat kanthi jeneng sing padha. Markdown akeh digunakake kanggo ngowahi format file readme, nalika nulis postingan forum, lan ing editor teks kanggo nggawe dokumen teks sing apik kanthi cepet. (Wikipedia: Markdown ) Teks sing diformat ing Markdown gampang banget diwaca. Macem-macem rasa Markdown digunakake ing Stack Overflow utawa GitHub kanggo ngowahi format konten sing digawe pangguna.

Instalasi

Kanthi gawan, alat Javadoc nggunakake komentar Javadoc kanggo ngasilake dokumentasi API minangka HTML. Proses iki bisa dikonfigurasi maneh nggunakake Doclets . Doclets minangka program Java sing nemtokake isi lan format file output alat Javadoc. Markdown-doclet ngganti Java Doclet standar lan kanthi mangkono menehi pangembang kemampuan kanggo nggunakake sintaks Markdown ing komentar Javadoc. Sampeyan bisa nginstal ing Maven nggunakake maven-javadoc-plugin. maven-javadoc-plugin 2.9 ch.raffael.doclets.pegdown.PegdownDoclet ch.raffael.pegdown-doclet pegdown-doclet 1.1 true

Nulis komentar ing Markdown

Sampeyan saiki bisa nggunakake sintaks Markdown kanggo nulis 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) { ... } Sawise eksekusi

mvn javadoc:Javadoc

document HTML API kui dumunung ing

target / situs / apidocs.

Dokumen sing digawe kanggo kode ing ndhuwur katon kaya iki: Nalika sampeyan bisa ndeleng saka gambar kasebut, komentar Javadoc wis diowahi kanthi sampurna dadi HTML.

Kesimpulan

Markdown nduweni kaluwihan sing jelas tinimbang sintaks Javadoc standar: luwih gampang diwaca ing kode sumber. Coba deleng sawetara komentar cara ing java.util.Map: akeh sing kebak tag format lan angel diwaca tanpa nggunakake alat tambahan. Nanging sampeyan kudu ngelingi yen Markdown bisa nyebabake masalah karo alat lan IDE sing mung bisa digunakake karo sintaks Javadoc standar. Sumber: Nggunakake sintaks Markdown ing komentar Javadoc saka mitra JCG kita Michael Scharhag saka blog mscharhag, Pemrograman lan Barang.