Terjemahan: Menggunakan sintaks Markdown dalam ulasan Javadoc

Menggunakan Sintaks Markdown dalam Komen Javadoc

Dalam siaran ini, kami akan melihat cara anda boleh menulis ulasan Javadoc menggunakan Markdown dan bukannya sintaks Javadoc standard. Jadi apa itu Markdown? Markdown ialah bahasa penanda mudah yang boleh diterjemahkan ke dalam HTML menggunakan alat dengan nama yang sama. Markdown digunakan secara meluas untuk memformat fail readme, semasa menulis siaran forum, dan dalam editor teks untuk mencipta dokumen teks yang cantik dengan cepat. (Wikipedia: Markdown ) Teks yang diformat dalam Markdown sangat mudah dibaca. Pelbagai perisa Markdown digunakan pada Stack Overflow atau GitHub untuk memformat kandungan yang dijana pengguna.

Pemasangan

Secara lalai, alat Javadoc menggunakan ulasan Javadoc untuk menjana dokumentasi API sebagai HTML. Proses ini boleh dikonfigurasikan semula menggunakan Doclets . Doclets ialah program Java yang menentukan kandungan dan pemformatan fail output alat Javadoc. Markdown-doclet menggantikan Java Doclet standard dan dengan itu memberikan pembangun keupayaan untuk menggunakan sintaks Markdown dalam ulasan Javadoc mereka. Anda boleh memasangnya dalam 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 ulasan dalam Markdown

Anda kini boleh menggunakan sintaks Markdown untuk menulis komen 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) { ... } Selepas pelaksanaan

mvn javadoc:Javadoc

dokumen HTML API yang dijana terletak di

sasaran/tapak/apidocs.

Dokumen yang dijana untuk kod di atas kelihatan seperti ini: Seperti yang anda lihat dari rajah, ulasan Javadoc ditukar dengan sempurna kepada HTML.

Kesimpulan

Markdown mempunyai kelebihan yang jelas berbanding sintaks Javadoc standard: ia lebih mudah dibaca dalam kod sumber. Lihat sahaja beberapa ulasan kaedah dalam java.util.Map: kebanyakannya penuh dengan teg pemformatan dan sukar dibaca tanpa menggunakan alat tambahan. Tetapi anda perlu ingat bahawa Markdown boleh menyebabkan masalah dengan alat dan IDE yang hanya boleh berfungsi dengan sintaks Javadoc standard. Sumber: Menggunakan sintaks Markdown dalam ulasan Javadoc daripada rakan kongsi JCG kami Michael Scharhag daripada blog mscharhag, Pengaturcaraan dan Bahan.