Markdown в комментариях Javadoc
Писать комментарии Javadoc на Markdown вместо HTML для лучшей читаемости.
Сравнение кода
✕ Java 8
/**
* Returns the {@code User} with
* the given ID.
*
* <p>Example:
* <pre>{@code
* var user = findUser(123);
* }</pre>
*
* @param id the user ID
* @return the user
*/
public User findUser(int id) { ... }
✓ Java 23+
/// Returns the `User` with
/// the given ID.
///
/// Example:
/// ```java
/// var user = findUser(123);
/// ```
///
/// @param id the user ID
/// @return the user
public User findUser(int id) { ... }
Заметили проблему в этом коде? Сообщите нам.
Почему современный подход лучше
Естественный синтаксис
Обратные кавычки для inline-кода и ``` для блоков вместо HTML-тегов.
Проще писать
Никакого {@code}, <pre>, <p>-тегов — просто пишите Markdown.
Лучше в редакторах
Markdown отлично отображается в современных IDE и текстовых редакторах.
Старый подход
Javadoc на основе HTML
Современный подход
Javadoc на Markdown
Начиная с JDK
23
Сложность
Начинающий
Поддержка JDK
Markdown в комментариях Javadoc
Доступно
Доступно с JDK 23 (сент. 2024)
Как это работает
Java 23 вводит комментарии Javadoc на Markdown с синтаксисом /// как альтернативу традиционному формату /** */ на основе HTML. Синтаксис Markdown более естественен для написания и чтения: поддерживаются блоки кода, выделение, списки и ссылки. Компилятор преобразует Markdown в HTML для вывода Javadoc.
Связанная документация
Доказательство