Pagsasalin: Paggamit ng Markdown syntax sa mga komento ng Javadoc

Paggamit ng Markdown Syntax sa Javadoc Comments

Sa post na ito, titingnan namin kung paano ka makakasulat ng mga komento sa Javadoc gamit ang Markdown sa halip na ang karaniwang Javadoc syntax. Kaya ano ang Markdown? Ang Markdown ay isang simpleng markup language na maaaring opsyonal na isalin sa HTML gamit ang tool na may parehong pangalan. Ang Markdown ay malawakang ginagamit upang i-format ang mga readme file, kapag nagsusulat ng mga post sa forum, at sa mga text editor upang mabilis na makalikha ng magagandang mga dokumento ng teksto. (Wikipedia: Markdown ) Napakadaling basahin ng text na na-format sa Markdown. Iba't ibang lasa ng Markdown ang ginagamit sa Stack Overflow o GitHub para i-format ang content na binuo ng user.

Pag-install

Bilang default, ginagamit ng Javadoc tool ang mga komento ng Javadoc upang bumuo ng dokumentasyon ng API bilang HTML. Maaaring muling i-configure ang prosesong ito gamit ang Doclets . Ang mga Doclet ay mga Java program na tumutukoy sa nilalaman at pag-format ng output file ng Javadoc tool. Pinapalitan ng Markdown-doclet ang karaniwang Java Doclet at sa gayon ay binibigyan ang developer ng kakayahang gumamit ng Markdown syntax sa kanilang mga komento sa Javadoc. Maaari mong i-install ito sa Maven gamit ang maven-javadoc-plugin. maven-javadoc-plugin 2.9 ch.raffael.doclets.pegdown.PegdownDoclet ch.raffael.pegdown-doclet pegdown-doclet 1.1 true

Pagsusulat ng mga komento sa Markdown

Maaari mo na ngayong gamitin ang Markdown syntax upang magsulat ng mga komento sa 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) { ... } Pagkatapos ng pagpapatupad

mvn javadoc:Javadoc

ang nabuong HTML API na dokumento ay matatagpuan sa

target/site/apidocs.

Ang dokumentong nabuo para sa code sa itaas ay ganito ang hitsura: Gaya ng nakikita mo mula sa figure, ang mga komento ng Javadoc ay perpektong na-convert sa HTML.

Konklusyon

Ang Markdown ay may malinaw na kalamangan sa karaniwang Javadoc syntax: mas madaling basahin sa source code. Tingnan lamang ang ilan sa mga komento ng pamamaraan sa java.util.Map: marami sa kanila ay puno ng mga tag sa pag-format at mahirap basahin nang hindi gumagamit ng mga karagdagang tool. Ngunit kailangan mong tandaan na ang Markdown ay maaaring magdulot ng mga problema sa mga tool at IDE na maaari lamang gumana sa karaniwang Javadoc syntax. Pinagmulan: Paggamit ng Markdown syntax sa Javadoc na mga komento mula sa aming kasosyo sa JCG na si Michael Scharhag mula sa mscharhag blog, Programming and Stuff.