В этом посте мы рассмотрим как можно писать комментарии Javadoc используя Markdown вместо стандартного синтаксиса Javadoc.

Итак, что такое Markdown?

Markdown – это простой язык разметки, который можно при желании перевести в HTML с помощью одноименного инструмента. Markdown широко используется для форматирования readme файлов, при написании сообщений на форумах, а также в текстовых редакторах для быстрого создания красивых текстовых документов. (Википедия: Markdown) Текст, отформатированный в Markdown, очень легко читается. Различные разновидности Markdown используются на сайтах Stack Overflow или GitHub для форматирования пользовательского контента.
Python-университет

Установка

По умолчанию инструмент 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.
Документ, сгенерированый для вышеприведенного кода, выглядит так: Перевод: Использование синтаксиса Markdown в комментариях Javadoc - 1 Как видно из рисунка, Javadoc комментарии прекрасно конвертируются в HTML.
Frontend-университет

Заключение

Markdown имеет явное преимущество перед стандартным синтаксисом Javadoc: он гораздо легче читается в исходном коде. Просто взгляните на некоторые комментарии к методам из java.util.Map: многие из них полны форматирующих тэгов и с трудом могут быть прочитаны без использования дополнительных инструментов. Но нужно помнить, что Markdown может вызвать проблемы с инструментами и IDE, которые умеют работать только со стандартным Javadoc синтаксисом.