В JavaDoc предложили добавить тег @note, чтобы важные предупреждения в API-документации не тонули в обычном описании методов и классов. По данным Habr / Новости, идея пока относится к JDK 28: команда OpenJDK собирает обратную связь, а синтаксис еще может измениться.
Суть предложения простая: разработчик сможет пометить важное примечание прямо в комментарии JavaDoc, а стандартный doclet превратит его в отдельный заметный блок. В примере из обсуждения используется конструкция с заголовком вроде Caution и текстом Untrusted input must be verified. Для API-документации это не косметика, а способ вынести критичную информацию туда, где ее сложнее случайно пропустить.
Сейчас похожие заметки обычно делают менее аккуратными способами: пишут предупреждение обычным текстом, вставляют HTML-разметку или используют нестандартные теги, которые зависят от конкретного проекта и настроек сборки документации. В итоге у команд получается зоопарк: где-то важное замечание выглядит как жирная строка, где-то как абзац с Warning, где-то теряется среди описания параметров и исключений.
Тег @note должен дать единый механизм для таких случаев. Заголовок блока можно будет менять, а через параметр javadoc -tag создавать собственные варианты, например @warning. Это полезно для библиотек, фреймворков и внутренних SDK, где документация часто становится единственным быстрым способом понять, можно ли вызывать метод с пользовательским вводом, какие есть ограничения потокобезопасности или почему seemingly harmless вызов внезапно открывает дверь в неприятности.
Для Java-разработчиков ценность здесь особенно приземленная. API-документация читается не как книга, а как справочник: открыл метод, проверил контракт, пошел дальше. Если предупреждение спрятано в длинном описании, его легко не заметить, особенно когда IDE показывает фрагмент JavaDoc во всплывающем окне. Отдельный блок повышает шанс, что важная ремарка действительно попадет в поле зрения, а не останется галочкой в совести автора документации.
Есть и организационный эффект. В больших командах единый формат предупреждений помогает ревьюерам и техлидам быстрее проверять публичные API. Вместо договоренности на уровне чата вроде пишем WARNING капсом и молимся можно закрепить понятный стиль в документации. Для компаний с платформенными командами это снижает шум: один формат для security-заметок, другой для ограничений производительности, третий для миграционных подсказок.
При этом предложение пока не означает, что тег @note гарантированно появится в финальной сборке JDK 28 именно в таком виде. OpenJDK еще собирает мнения, а детали синтаксиса могут поменяться. Это нормальная стадия для изменений в инструментарии Java: сначала проверяют, достаточно ли распространена боль, не ломает ли нововведение существующие практики и не превращается ли маленький тег в еще один повод спорить о стиле документации на каждом ревью.
Если идея дойдет до релиза, JavaDoc получит небольшое, но практичное улучшение: не новый язык, не очередной фреймворк поверх фреймворка, а более внятный способ сказать читателю API: вот это место действительно важно. Для экосистемы Java такие изменения часто работают лучше громких анонсов, потому что экономят минуты каждый день и ошибки каждый квартал.