JavaRush /Java блог /Архив info.javarush /Перевод: Использование синтаксиса Markdown в комментариях...
Helga
26 уровень

Перевод: Использование синтаксиса Markdown в комментариях Javadoc

Статья из группы Архив info.javarush

Использование синтаксиса 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.
Документ, сгенерированый для вышеприведенного кода, выглядит так: Перевод: Использование синтаксиса Markdown в комментариях Javadoc - 1 Как видно из рисунка, Javadoc комментарии прекрасно конвертируются в HTML.
Заключение
Markdown имеет явное преимущество перед стандартным синтаксисом Javadoc: он гораздо легче читается в исходном коде. Просто взгляните на некоторые комментарии к методам из java.util.Map: многие из них полны форматирующих тэгов и с трудом могут быть прочитаны без использования дополнительных инструментов. Но нужно помнить, что Markdown может вызвать проблемы с инструментами и IDE, которые умеют работать только со стандартным Javadoc синтаксисом. Источник: Using Markdown syntax in Javadoc comments от нашего JCG партнера Michael Scharhag из блога mscharhag, Programming and Stuff.
Комментарии
ЧТОБЫ ПОСМОТРЕТЬ ВСЕ КОММЕНТАРИИ ИЛИ ОСТАВИТЬ КОММЕНТАРИЙ,
ПЕРЕЙДИТЕ В ПОЛНУЮ ВЕРСИЮ