Переклад: Використання синтаксису Markdown у коментарях Javadoc

Використання синтаксису Markdown у коментарях Javadoc

У цьому пості ми розглянемо як можна писати коментарі Javadoc, використовуючи Markdown замість стандартного синтаксису Javadoc. Отже, що таке Markdown? Markdown – це звичайна мова розмітки, яку можна за бажання перекласти в HTML за допомогою однойменного інструменту. Markdown широко використовується для форматування readme файлів, при написанні повідомлень на форумах, а також текстових редакторах для швидкого створення красивих текстових документів. (Вікіпедія: Markdown ) Текст, відформатований у Markdown, дуже легко читається. Різні різновиди Markdown використовуються на сайтах Stack Overflow або GitHub для форматування контенту користувача.

Встановлення

За замовчуванням інструмент Javadoc використовує коментарі Javadoc для генерації API документації у вигляді HTML. Цей процес можна переналаштувати за допомогою Doclets . Doclets – це Java програми, які задають зміст та спосіб форматування вихідного файлу інструменту Javadoc. Markdown-doclet замінює стандартний Java Doclet і цим дає розробнику можливість використовувати Markdown синтаксис у своїх Javadoc коментарях. Встановити його в Maven можна за допомогою maven-javadoc-plugin. maven-javadoc-plugin 2.9 ch.raffael.doclets.pegdown.PegdownDoclet ch.raffael.pegdown-doclet pegdown-doclet 1.1 true

Написання коментарів у Markdown

Тепер можна використовувати Markdown синтаксис для написання коментарів 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) { ... } Після виконання

mvn javadoc:Javadoc

згенерований HTML API документ розміщується за адресаою

target/site/apidocs.

Документ, згенерований для наведеного вище коду, виглядає так: Як видно з малюнка, Javadoc коментарі прекрасно конвертуються в HTML.

Висновок

Markdown має явну перевагу перед стандартним синтаксисом Javadoc: він набагато легше читається у вихідному коді. Просто погляньте на деякі коментарі до методів з java.util.Map: багато з них повні форматуючих тегів і важко можуть бути прочитані без використання додаткових інструментів. Але слід пам'ятати, що Markdown може викликати проблеми з інструментами та IDE, які вміють працювати лише зі стандартним Javadoc синтаксисом. Джерело: Using Markdown syntax in Javadoc comments від нашого партнера JCG Michael Scharhag з блогу mscharhag, Programming and Stuff.