В этом посте мы увидим, как мы можем писать комментарии Javadoc, используя Markdown вместо типичного синтаксиса Javadoc.
Так что же такое уценка?
Markdown — это синтаксис форматирования простого текста, разработанный таким образом, что при желании его можно преобразовать в HTML с помощью инструмента с тем же именем Markdown широко используется для форматирования файлов readme, для написания сообщений на онлайн-форумах или в текстовых редакторах для быстрого создания форматированных текстовых документов.
(Википедия: Уценка )
Markdown — это очень легко читаемый синтаксис форматирования. Различные варианты Markdown могут использоваться в Stack Overflow или GitHub для форматирования пользовательского контента.
Настроить
По умолчанию инструмент Javadoc использует комментарии Javadoc для создания документации API в форме HTML. Этот процесс может быть настроен для использования
Доклеты Доклеты — это Java-программы, которые определяют содержимое и формат вывода инструмента Javadoc.
Markdown-doclet является заменой стандартного Java Doclet, который дает разработчикам возможность использовать синтаксис Markdown в своих комментариях Javadoc. Мы можем настроить этот доклет в Maven, используя maven-javadoc-plugin .
01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
|
< build > < plugins > < plugin > < artifactId >maven-javadoc-plugin</ artifactId > < version >2.9</ version > < configuration > < doclet >ch.raffael.doclets.pegdown.PegdownDoclet</ doclet > < docletArtifact > < groupId >ch.raffael.pegdown-doclet</ groupId > < artifactId >pegdown-doclet</ artifactId > < version >1.1</ version > </ docletArtifact > < useStandardDocletOptions >true</ useStandardDocletOptions > </ configuration > </ plugin > </ plugins > </ build > |
Написание комментариев в Markdown
Теперь мы можем использовать синтаксис Markdown в комментариях Javadoc:
01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
|
/** * ## 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 . Многие комментарии Javadoc заполнены тегами форматирования и едва читаемы без какого-либо инструмента. Но имейте в виду, что Markdown может вызвать проблемы с инструментами и IDE, которые ожидают стандартного синтаксиса Javadoc.
Ссылка: | Использование синтаксиса Markdown в комментариях Javadoc от нашего партнера по JCG Майкла Шаргага в блоге mscharhag, Programming and Stuff . |