Статьи

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

Ноябрь 23, 2018

В этом посте мы увидим, как мы можем писать комментарии 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 .
35
Share: