С выходом Java 23 произошли важные изменения в формате написания комментариев — теперь они могут быть написаны с использованием
Markdown. Ранее разработчики использовали HTML и JavaDoc-теги для оформления таких комментариев, что могло создавать сложности, особенно для тех, кто не знаком с HTML. Теперь, благодаря поддержке Markdown, комментарии станет писать проще и удобнее.Зачем это нужно?
HTML с течением времени стал менее популярен для ручного написания. Сегодня чаще используют языки разметки, ориентированные на удобство разработчиков. Использование HTML для JavaDoc создавало трудности, так как он тяжеловесен и сложен для быстрого написания, особенно для новых разработчиков.Преимущества использования Markdown
Markdown стал популярным благодаря своей простоте и удобочитаемости. Он идеально подходит для написания JavaDoc, которая обычно состоит из текстовых блоков, списков, ссылок и выделенного текста. Вместо сложных HTML-тегов можно использовать гораздо более лаконичные конструкции Markdown.Вот так выглядит комментарий к методу
hashCode с использованием HTML и JavaDoc-тегов:
/**
* Возвращает хэш-код для объекта.
* <p>
* Общий контракт метода {@code hashCode}:
* <ul>
* <li>Если метод вызывается несколько раз на одном объекте в ходе выполнения программы,
* он должен возвращать одно и то же значение, если данные объекта не изменялись.
* <li>Если два объекта равны, вызов метода {@code hashCode} должен вернуть одинаковое значение.
* <li>Если объекты не равны, метод может возвращать одинаковые хэш-коды, но этого следует избегать.
* </ul>
* @return хэш-код для объекта.
*/
Этот же комментарий в
Markdown:
/// Возвращает хэш-код для объекта.
///
/// Общий контракт метода `hashCode`:
///
/// - Если метод вызывается несколько раз на одном объекте в ходе выполнения программы,
/// он должен возвращать одно и то же значение, если данные объекта не изменялись.
/// - Если два объекта равны, вызов метода `hashCode` должен вернуть одинаковое значение.
/// - Если объекты не равны, метод может возвращать одинаковые хэш-коды, но этого следует избегать.
///
/// @return хэш-код для объекта.
Для использования
Markdown введён новый формат комментариев: строки начинаются с трёх слэшей (`///`), вместо традиционного синтаксиса /** ... */. Основные различия:
- Пробел между абзацами обозначается пустой строкой, как и в
Markdown.- Списки создаются с помощью маркеров - вместо
HTML-тегов <ul> и <li>.- Подчёркивание (`_`) используется для выделения текста, вместо
HTML-тегов <em>.- Теги вроде {@code} заменяются обратными апострофами (\`...\`).
В то же время, важные теги, такие как @param и @return, сохраняются и могут использоваться вместе с
Markdown-разметкой.🔗 С полным описанием JEP можно ознакомиться по ссылке: https://openjdk.org/jeps/467
#Java #JEP