В JavaDoc предлагают добавить тег @note. Он позволит выделять важные примечания прямо в документации api.

/**
 * {@note (header='Caution:')
 * Untrusted input must be verified!}
 */

Стандартный doclet превратит такую запись в отдельный заметный блок. Заголовок можно менять, а через javadoc -tag разрабатывать свои варианты вроде @warning.

Сейчас для подобных вещей приходится использовать обычный текст, HTML или нестандартные теги. @note даст единый метод отделить важное замечание от простыни документации.

Пока это только предложение для JDK 28. Команда OpenJDK собирает обратную связь, поэтому до релиза синтаксис ещё может измениться. 

Все для людей!

Присоединяйтесь к русскоязычному сообществу разработчиков на Spring Boot в телеграм — Spring АйО, чтобы быть в курсе последних новостей из мира разработки на Spring Boot и всего, что с ним связано.