Новая аннотация javadoc @apiNote

Я нашел новый и недокументированный тег javadoc в LongStream документации по классам. Теги javadoc @apiNote, по-видимому, используются для подробного объяснения метода, но там нет документации или заметок о выпуске этого тега.

Какова его истинная цель? Где его документация?

Скомпилированный пример javadoc с использованием @apiNote можно найти в Уменьшить документацию по методу

Ответы

Ответ 1

Я бы сказал, что они теперь "официальные", если не стандартные. Смотрите JDK-8068562. Как отметил Николай выше, его блог Новые теги Javadoc @apiNote, @implSpec и @implNote дает отличный обзор. Они поддерживаются Netbeans, а недавно Content Assist в Eclipse распознает их. Они обсуждаются и рекомендуются в Effective Java, третье издание. Они используются во всем исходном коде библиотеки Java.

Ответ 2

Из элемента списка рассылки, цитируемого @bargenson:

Эти теги активируются с помощью функции -tag в командной строке инструмента javadoc. Они не предлагаются в качестве стандартных тегов javadoc и могут быть реализованы по-разному в будущих выпусках Java. Поскольку они реализованы как пользовательские теги только для документации API JDK, вы не можете автоматически использовать их в своем собственном коде. (Вы можете, конечно, добавить те же параметры командной строки в свои javadoc-вызовы, если вам нравятся эти теги).

Таким образом, они не являются стандартными тегами Javadoc вообще.