В этом посте мы рассмотрим как можно писать комментарии 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.
Теперь можно использовать 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 синтаксисом.
Как видно из рисунка, Javadoc комментарии прекрасно конвертируются в HTML.
ПЕРЕЙДИТЕ В ПОЛНУЮ ВЕРСИЮ