В JavaDoc предлагают добавить заметки, которые сложно пропустить
habr.comВ JavaDoc предлагают добавить тег @note. Он позволит выделять важные примечания прямо в документации API.Стандартный doclet превратит такую запись в отдельный заметный блок.
Заголовок можно менять, а через javadoc ‑tag создавать свои варианты вроде @warning.Сейчас для подобных вещей приходится использовать обычный текст, HTML или нестандартные теги. @note даст единый способ отделить важное замечание от простыни документации.Пока это только предложение для JDK 28.
